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standard diskette) 
FREEBUF (SVC 6) (Interaction 6-19 
with GET/FREEHEAP SVCs) 
UNLINK (SVC 15) (Enhanced 6-22 
processing) 
CHECK (SVC 17) (IOSW in Regs 6-25 /6-28 
O and 1) 
CHECK (SVC 17) (TC event) 6-26/6-28 
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CHAPTER 1; INTRODUCTION 


The Wang VS Virtual Memory Operating System is intended as a 
low-overhead multiprogramming system for a medium-sized business 
machine configuration. As such, the design emphasis is on small 
size and simplicity of operation. This is apparent in many of 
the system's components: a simple scheduler, conventional 1/0 
system, limited segmentation and memory protection capability, 
etc. On the other hand, facilities such as ANSI COBOL (1974), 
indexed file support, hierarchical file directory structures, and 
a large address space supported by an efficient paging mechanism 
make the system competitive with many larger computers. 


The programmer should understand what the various system 
components are, how they interface with his program, what the 
(virtual) memory is used for and how it is partitioned for 
various purposes, and what certain operating system data 
structures (control blocks) contain. The purpose of this 
document is to provide this information. 


Figures 1-1, 1-2, and 1-3 which follow are overall views of 
virtual memory and of the operating system's control block 
structure, and are provided for reference while reading the text 
of the document. 
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End resident 
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256K 
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Figure 1-1. 


(SYSTEM SEGMENT - PROTECTED FROM USER MODIFICATION 
- ADDRESSABLE FROM ALL TASKS) 


--> 


--> 


Fixed low storage 
(Old and new PCWs, IOCAs, IOSW, system work 
area) 


Directly addressable system area (to byte 
4096) , code and control blocks 

Additional resident system code and control 
blocks (variable) 


System Free storage pool, allocatable by 
GETMEM (ends on full page boundary) 


System transient (paged) 
code and data 


Unused and unaddressable pages 


Virtual Memory Map - Segment 0 (System Segment) 


i=2 


Segment 1 (USER REENTRANT PROGRAM SEGMENT - PROTECTED FROM 
USER MODIFICATION - ADDRESSABLE FROM ONE OR MORE 


TASKS) 
1024K+0 | Length of program text area (8*n) 
1024K+4 ! oatee eeinuranar eae eee 
1024K+8 pene eae. @ isubievoniss _ | 
024K+8n+8 ae ot Vatatie® initial values Bick” _ 
| (4 bytes) 


| bytes) 


| Linkage block (variable) 
No more than --> 


1024K+512K 


Figure 1-2. Virtual Memory Map-Segment 1 (User Program Segment) 


Segment 2 (USER MODIFIABLE SEGMENT - NOT PROTECTED 
- ADDRESSABLE FROM ONE TASK) 


2048K | File buffer area (initially no space 
| reserved - stack limit increased by full 
| pages to acquire space) 
2048K+2aK “> [-r- ee eee emer ee er em crm er eer eo 
(stack limit) | Unused stack space (contents unreliable to a 
| user program) 
Stack top “> |--e-t- ee ere ter re eee ewe 
pointer varies | Stack (grows downward - toward 2048K - may 
| not pass stack limit) 
Register R14 <So>5 24 eS ee ee ee ee See ey ee 
contains this | Static areas (some of which may be 
address on. | initialized), as addressed by user's program 
program entry | through RCONs and register 14 


| Preceding (LINKed-from) program invocations' 
| stack and static areas 


A few words which should not be modified by 
a user's program (task-related system 
information) 


No more than --> 
2048K+512K 


Figure 1-3. Virtual Memory Map-Segment 2(User Modifiable Segment) 


CHAPTER 2: STANDARDS 


2.1 PROGRAMMING 


This section describes conventions which must be followed in 
writing code for the system in order to insure its successful 
execution and maintainability. 


2.1.1 User Programs 


These include system utilities which do not require special 
privileges, and data management routines which execute in an 
environment similar to that of normal user programs. Programmers 
writing entirely in a higher-level language (e.g., COBOL) need 
not learn all the details of these conventions, but should be 
aware of the standards for use of the workstation. 


2.1.1.1 Constraints on Code and Data 
For the following discussion, these definitions will be used: 


Program - An entity either invoked by the command processor or by 
a LINK. This may be composed of several modules. 


Object Program - The representation of a program on the disk 
after being processed by a compiler or linker. 


Module - An individual assembled or compiled portion of a 
program. A program consists of one or more modules. 


"Static' Area - This is the special area that has the property of 
appearing to be statically assigned space to a program using it. 
This space is allocated on a program basis and released on _ the 
same basis. The system will pre-initialize this area for the 
program with initial values specified in the object program. 


2.1.1.1.1 The Reentrant Program Segment 


User programs in segment one will be reentrant (may not modify 
themselves). All programs activated by the RUN command on the 
LINK SVC routine will be entered at the address specified in 
virtual location 1024K+4 (segment one, page zero, displacement 
four). Programs of up to 512K (K=1024) bytes (the full segment 
one) can be supported. The reentrancy requirement suggests’ the 
necessity of a separate modifiable area for variable data items, 
and the necessity of dynamically initializing variables in this 
modifiable area. This modifiable area is discussed in the 
following paragraphs. The only other constraints on aé_éeuser 
program are that it must follow the standard conventions for 
making requests of the supervisor, transferring control between 
and within programs, and accepting and passing parameters. These 
conventions are described elsewhere in this document. 


2.1.1.1.2 The Modifiable Segment 


Although more than one user of the system may be sharing the code 
of the same program, each has a separate modifiable area. This 
area is organized as a single linear pushdown list (stack) which 
is entirely within segment 2 of the user program's virtual 
address space and which extends to address 2048K+n (n < 512K). 
The stack base (bottom-of-stack) is 2048Ktnt+t1. The stack limit 
(lowest allowed stack location, addressed by control register 2) 
is 2048K plus a varying amount (between 0 and 128K) reserved for 
I/O buffers and other unprotected, ‘heap'-allocated data areas. 
The stack grows downward. (See the VS Principles of Operation, 
Stack Oriented Instructions.) Proceeding downward, we have, on 
entry to a program: 


(1) An unspecified number of bytes of system information, 
which should not be modified by the user program. 


(2) An unspecified amount of information used by ‘UNLINK' 
during final return from the program. 


(3) 'Static' data areas as defined in the object format of 
the program to be initiated (see below). 


(4) A save area containing register contents and a return 


point for final return from the program by means of the 
"RETURN' macroinstruction or ‘RTC 15‘. 


NOTE: 


The ‘stack base' is defined to be the next 
byte above (1). 


Thus there may be many bytes of information on the stack when the 
user program is entered. Before the program uses any of the 
modifiable area other than the part containing this information, 
it must use one of the PUSH-type instructions to decrement 
general register 15 and thereby acquire additional space (this 
space being "pushed onto the stack"). Modifiable data items 
which are not to be treated in a stack-oriented manner should 
normally have space reserved for them at compilation time (by 
defining them in a 'static' area) or immediately on program 
initiation (either by pushing their initial values onto the stack 
or by reserving space with the PUSHN instruction), so that the 
rest of the stack may be used for stack-oriented data. 


2.1.1.1.3 Creation of 'Static' Areas 


The system supports a method for obtaining initialized or 
uninitialized '‘static' memory on the stack. This support is 
invoked every time a new program is invoked by the RUN command or 
by a LINK, and not at any other time. Basically the support will 
assign an area of memory on the stack as the ‘static’ area. The 
size of the assigned area is determined by the size requested in 
the object module. Locations in this area that are to have 
initial values will then have them copied from the initial value 
section of the program's object module. Note that this 
allocation and initialization of memory will take place only when 
the program is started by the command processor or when the 
program is invoked by LINK. This means that program CALLs within 
the object program will not cause memory to be allocated or 
initialized. 


When a program is initiated, either by the RUN command or LINK, 
register 14 will point to the lowest address of that object 
module's ‘static’ areas. Each program is expected to refer to 
particular ‘static’ areas through the following convention: 


A special type of address constant (RCON) may be written in a 
program, naming a 'static' area, which is resolved to _ the 
displacement of that ‘static’ area from the address passed to the 
program in register 14. Thus the program can add the value in 
such an address constant to the contents of register 14 and _ then 
use the result to address a ‘static’ area. 


When a LINK is performed, the issuer's 'static' areas are not 
changed. When the issuing program is returned,its initialized 
‘static’ area contents are still available. The LINKed-to 
program, if it has a request in the object module for a ‘static’ 
area, will receive a fresh area on the stack. This area will 
remain for the LINKed-to program until it returns to the program 
which issued the LINK. Addresses of locations in the LINK 
issuer's ‘static' areas will not be passed to programs invoked by 
LINK except as the program itself passes such an address. If 
LINK issuer wants, it can pass addresses in any of its ‘static’ 
areas, but a LINKed-to program cannot either pass_ back 
information in its 'static' areas or expect that values placed in 
its ‘static' areas will be maintained between its invocations by 
LINK. 
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This system requires support on each of three levels: 
(1) Compile or assemble time 
(2) Linker (linkage editor) time (if binding is required) 


(3) Program start-up time (either LINK or the RUN command 
initiating the program). 


The support required at each step is: 


Compile Time 


The compiler or assembler has the responsibility to supply 
in the object program all information necessary to support 
this feature. To do this, the compiler will have to 
segment the program information and the data that is to be 
in a 'static' area. If the program is to be runable 
without having to bind (linkage edit), all references to 
addresses in 'static' areas will have to be specified as 
displacements into the block of ‘static’ areas for this 
object program. 


When data is to be used from the ‘static" area, the program 
will load a register with the value in the address constant 
which contains the displacement of the desired data, and 
will add the contents of register 14 to this value. 


Binding Time 


The linker (linkage editor) will collect the ‘static’ data 
sections from all the subprograms. If two or more 
subprograms have static sections with the same name, the 
initial values from the first of these sections will be 
used and the length of the resulting section will be the 
length of the longest of these sections. 


Program Start-up Time 


The same mechanism will be used with programs started by 
the command language and programs invoked by LINK. The 
mechanism will perform the services only at the time of the 
program invocation and not at any subsequent internal CALLs 
or program RETURNs. 


At program start-up time, the system will: 


a. Push onto the stack an area equal to the total size of 
‘static’ sections as defined in the object program. 


b. Copy values from the object program to the correct 
locations in each new ‘static’ section. This is not a 
simple move loop. The data is stored in the object 
program in a compressed format. It has values only for 
the areas that need initial values. Each initial value 
in the object program has with it a displacement into 
the whole block of 'static' sections. 


c. Set register 14 to address the first byte of this area. 
d. Perform additional program invocation processing. 
2.1.1.1.4 Address Constants 


There are three types of address constants permitted in a 
program: A, V and R type. 


The A type is used for addresses of items within the same 
compilation or assembly. These may be the labels of instructions 
or constants, or may be addresses relative to either of these. 
Type A constants may be only in a program and refer to the 
program itself. Some examples are: 


L DC A(L) ADDRESS OF ITSELF 
B DC A(L+2) ADDRESS RELATIVE TO ‘L' 


The V_ type of address constant can be used to refer to locations 
known only by their external names. These names are normally in 
code areas or 'static' areas provided by another assembly or 
compilation. 


Both these types (A and V) can be used in the code area (segment 
1) to point to other code areas, but cannot be in the code area 
(segment 1) pointing to a 'static' area. (This restriction is 
caused by the constraint that no location in segment 1 can be set 
to a value differing from that on the program file from which it 
will be paged. The starting address of a ‘static’ area is 
unknown until the program starts running. For the address to be 
relocated in the program, it would involve modifying locations in 
the code area.) The system will, however, support address 
constants in the 'static' area that reference locations in either 
a code area or in other 'static' areas. 


Q w 
& 


F STATIC 
DC 
DC 
DC 


G: STATIC 

Gl DS 

G2 DS 
ENTRY 


I STATIC 
DC 
DC 
DC 


END 


A(B) 


3F 
G2 


V (F) 
V (G2) 
V(B) 


Name of code area (external name) 


Refer to location in same code area 
Makes B an external name 


Refer to location in another code area 


Name of 'static’ area (external name) 
Refer to location in a code area 

Refer to location in this 'static' area 
Refer to location in another ‘static’ area 


Name of ‘static’ area (external name) 


Makes G2 an external name 


End of this assembly 


Refer to a ‘static’ area in another assembly 
Refer to a location in such a ‘static’ area 
Refer to a location in a code area of 
another assembly 


End of this assembly 


The R type address constant is used by the program to _ locate 
‘static' areas. Because the program does not know the starting 
address of a ‘static’ area either when the program is compiled or 
linked, a method is needed to calculate the absolute address of a 
‘static’ area (or of a location within a ‘static’ area) using a 
relative address in the program. When the program is initiated, 
register 14 will have the absolute address of the start of the 
block of static areas. Each R type address constant will contain 
the displacement into the whole block of ‘static’ areas (created 
by program initiation or LINK) of the named ‘static’ area or 
location within a ‘static’ area. The program will add_ the 
displacement in the R type address constant to the value in 
register 14. This will give the address of the item. 


PROGR CODE 
* INSTRUCTIONS TO ADDRESS A ‘STATIC’ AREA 
LR R2,R14 STATIC BASE 
AL R2,RDATA PLUS STATIC AREA DISPLACEMENT 
GIVES ACTUAL ADDRESS OF 
‘STATIC' AREA 
USING DATA ,R2 
RDATA DC R (DATA) DISPLACEMENT OF *STATIC' 
SECTION ‘DATA‘ 
DATA STATIC 
DATAITEM oo F'5' 
END 


A more thorough example of assembler language source coding 
utilizing a ‘static’ area follows: 


REGS »EQUATE REGISTERS 
PROG CODE START A CODE SECTION 
BALR R3,0 GET ADDRESSABILITY 
USING *,R3 
* 
L R1 ,ADDWORD GET ADDRESS OF CONSTANT 
L R2,0(R1) GET CONSTANT 
¥ 
* FOLLOWING CODE USED TO 
¥ ADDRESS A ‘STATIC’ AREA 
¥ 
LR R2 ,R14 STATIC AREAS BASE 
AL R2 ,RCON ADDRESS AREA 'ST1' 
USING ST1,R2 
ST R3 ,DAT1 STORE CONSTANT IN 'STATIC' AREA 
SR RO,RO SET RETURN CODE TO ZERO 
RTC 15 RETURN TO CALLER 
- 
ST1 STATIC ESTABLISH 'STATIC' AREA NAMED 
¥ ‘sT1' 
DS 8F 
DAT1 DS F 
* 
PROG CODE RESUME THE CODE SECTION 
ADDWORD DC A (CONT) ADDRESS OF DATA CONSTANT 
CONT DC F'123' 
RCON DC R(ST1) DISPLACEMENT OF STATIC AREA 
¥ "ST1' WITHIN BLOCK OF ALLOCATED 
* STATIC AREAS 
END 
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2.1.1.1.5 Using The Assembler for 2200VS Object Code 


While the 2200VS Assembler language is closely modeled after the 
IBM 360/370 Assembler language, there are some important 
differences, the most obvious of which is the addition of several 
instructions and the dropping of others. There are a few items 
that have changed in the conventions beyond the instructions. 


To assemble a program, the following conventions are to be 
observed: 


1. The first statement in a program should be a CODE 
statement. This will cause the text following it to be 
part of the reentrant program section named by the CODE 
statement. The CODE statement can be used the same as 
the IBM 360 assembler CSECT statement. The CSECT 
statement is not used on this system. 


2. If a static area is desired, the STATIC statement 
should be used. The assembler allows any number of 
these statements and will allow initial values to be 
specified. 


Rules for pseudo-instructions unique to the 2200VS are: 
1. label CODE Not used; should be blank 


The label is required and must be a maximum of eight 
characters. It will be used as the external name of 
this reentrant program section. Note: ENTRY symbols 
in CODE or STATIC sections also are limited to eight 
characters. 


2. label STATIC Not used; should be blank 
The label is required and must be a maximum of eight 
-characters. It will be used as the external name of 
this 'static' section. 


2.1.1.2 Transfer of Control 


The modifiable area is also used in the course of transferring 
control between routines and programs in three ways: 


(1) The BAL, BALR, BALCI, BALS or JSCI instructions may be 
used within a program to save a return point in a 
register or on the stack and enter a subroutine. The 
BC, BCR, BCS or RTC instructions are used to return. 


29 


(2) 


(3) 


(4) 


The SVC instruction is used to request services from 
the supervisor, and save the general registers on _ the 
stack before initiating the service routine. When the 
supervisory service has been performed, return to. the 
user's program is effected by executing an SVCX 
instruction (in the supervisor). The user's program is 
concerned with nothing more than placing the address of 
required arguments (or occasionally the arguments 
themselves) on the top of the stack and issuing the SVC 
instruction. Routines entered by SVC instruction 
normally remove their input arguments and leave outputs 
on the top of the stack. Programmers interested in the 
details of the resulting stack manipulations may 
consult Figures 2-2 and 2-3. Figure 2-1 shows’ the 
associated register conventions which a user program 
must respect. 


The JSCI instruction is used to initiate a transfer of 
control between subprograms which have been bound 
together into a single program by the linker program. 
(Transfer of control between subprograms not bound 
together may be effected by LINK, as in (4) below.) 
The macroinstruction which generates the  JSCI 
instruction is referred to as 'CALL'. Figure 2-4 shows 
the sequence of instructions (available as a 
macroinstruction) which is used to effect this transfer 
of control, and the resulting items pushed onto the 
stack. 


The LINK SVC is used to initiate a transfer of control 
between programs not bound together by the linker 
program. The LINKed-to program should return to the 
issuer by means of the same RETURN sequence (also in 
Figure 2-4) used in conjunction with CALL. The user 
should note that LINK will result in stack 
modifications which do not occur with CALL. see 
section 2.1.1.1.3, ‘Creation of Static Areas', for a 
discussion of this. 
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Registers 


SP=15 Stack top pointer RESERVED (see Note 1) 
R14=14 General (used to address ‘static’ areas) 
R13=13} 


} 
} General use 
, } (Rl is argument list pointer for use with CALL or 
} LINK, by convention) 

} 


Note 1. Register 15 (SP) must always address the lowest 
location on the stack which contains usable data or 
into which data may be placed by any non-PUSH-type 
instructions. This constraint is imposed on all 
programs. 


Figure 2-1. 
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Figure 2.2. | 


END ADDRESSABLE -——3> 


SEGMENT 2 PRECEDING 
STACK 
IN USE 
ati SVC SAVE AREA 
FOR ‘LINK’ SVC 
SET BY ‘STATIC’ AREA 
‘LINK’ SAVE AREA FOR PROGRAM 
ONLY FOR ‘LINK’ 
ese, 
SAVE FOR BACK CHAIN 
LINK’, ‘CALL REGISTERS 0-14 
OR SVC SAVE AREA 
Eetoresieeee SP ON PROGRAM ENTRY 


WORK AREA 
PUSHED ONTO 
STACK BY 
PROGRAM 


Address for Return 
SAVE AREA BACK CHAIN 


ONTROL REGISTER 1 Soe ent REGISTERS 0-14 
IBACK CHAIN HEAD! SAVE AREA <@— SP ON SUBROUTINE ENTRY 


WORK AREA 
PUSHED ONTO 
STACK BY 
CALLED 
SUBPROGRAM 


“@— STACK TOP POINTER (SP) 


<&— STACK LIMIT POINTER 
(CONTROL REGISTER 2) 
ON PAGE BOUNDARY 


1/0 
BUFFER 
AREA 


(EXPANDS 


UPWARD) 


ADDRESS 2,097,152 ——p> 
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Stack linkage item after SVC entry: 


Byte 

68 PCW (status) 

64 PCW (return) with SVC number 

60 Back chain to next outer-more SVC save area or CALL/LINK 

save area 

56 Reg 14 save 

52 Reg 13 save 

48 Reg 12 save 


0-47 Regs 0-11 save 


Entry to SVC: Svc (SVC#) 
Exit from SVC: SVCX (Register) 
Figure 2-3. 
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Stack linkage item after CALL: 


Byte 

64 Address of return point 

60 Back chain to previous CALL/LINK save area 
0-59 Regs 0-14 save 


CALL: JSCI 15 ,=A(Entry-point) 
RETURN: LA 0,return-code 
RTC 15 (if unconditional) 


Note that the value of register 0 saved by JSCI is not restored 
to the register by RTC. 


Figure 2-4. 
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CALL 
Linkage by: JSCI condition, indirect-word-address 
Exit by: LA 0 ,Return-code 

RTC Condition 


| | 

| Registers | BEFORE | ON ENTRY [BEFORE EXIT|AFTER RETURN| 
| | | | | i 
| | | | [ | 
| RO lIrrelevant |As BEFORE {Irrelevant |Return-code | 
| | | | | 
| Rl [Argument list|As BEFORE [Irrelevant |As BEFORE* | 
| | pointer | | | | 
| | | | | | 
| R14 |*Static' baselAs BEFORE |Irrelevant |As BEFORE* | 
| | pointer** =| | | | 
| | | | | | 
| SP [Stack top {Updated stack top|Irrelevant |As BEFORE* | 
| | | | 
| Other [Irrelevant |As BEFORE lIrrelevant {As BEFORE* | 
| | | | | | 
| | | | | | 
| (Control (|Previous savelNew save area [As ON ENTRY|As BEFORE | 
[register 1)| area pointerl pointer (same as| | | 
| | | SP) | | | 
| | 


* 


Unless current save area is modified before return. 


wae Not enforced by the system. Register 14 may be used for 
other purposes by the user program if appropriate. 


Figure 2-5. 
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LINK 

Linkage by: SVC LINK 

Exit by: LA 0 ,Return-code 
RTC Condition 


Seo octet ee eR eke EE cee en 0 Re ER am 


| | 

| Registers | BEFORE | ON ENTRY |BEFORE EXIT| AFTER RETURN| 

| | | | | 

| | | | | | 

| RO | Irrelevant |As BEFORE* [Irrelevant |Return-code 

| | | | | 

| R1 [Argument list |As BEFORE [Irrelevant |As BEFORE 

| | pointer | | | 

| | | | | 

R14 |'Static' base |New 'static' base|Irrelevant |As BEFORE 

| | pointer**** | pointer | | 

| | | | | 

| SP [Stack top (LINK|Updated stack |Irrelevant |As 

| parameters) | top | | BEFORE**?* 

| | | | | 

| Other {Irrelevant {As BEFORE [Irrelevant |As BEFORE 

| | | | 

| | | | 

|(Control |Previous save |New save area [As ON ENTRY|As BEFORE 

|register 1)! area pointer | pointer (same as| | 

| | SP) | | 

| | | | 

* Program entry point address in register RO if LOADONLY 
option specified. 

sear New ‘static’ areas, UNLINK information, register save 


area, return address on stack. 


wires But LINK parameters popped from stack (see SVC LINK 
description). 


WII Not enforced by the system. 


Figure 2-5. (continued) 
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2.1.1.3 Supervisor Interface 


As mentioned briefly above, the SVC instruction is used as the 
normal interface between user programs and supervisory routines. 
In addition to the effect of the supervisory service request 
saving status information on the stack, as in Figure 2.3 above, 
there are four points which the writer of SVC routines and of 
system programs in user program mode should be aware of: 


(1) The top word of the stack should address an argument 
list when the SVC is executed if the arguments for the 
particular SVC are sufficiently many or sufficiently 
long that passing them directly on the top of the stack 
is infeasible. 


(2) Register 15 (SP) is generally the only register which 
must contain useful information when the SVC 
instruction is executed. 


(3) Corresponding to most valid SVC numbers are 
macroinstructions which may be used in assembly 
language programming to generate the SVC and pass its 
arguments. These macroinstructions are described in 
Chapter 4 of this document. 


(4) All registers except register 15 (SP) are restored on 
return from an SVC routine. When an argument list is 
provided, results may be returned in one of the 
arguments. In order to do this, the argument list must 
be in a user's modifiable data area or in the system 
area (segments 2 or 0). Otherwise results are returned 
on the top of the stack, replacing all input arguments. 


2.1.1.4 Standard Argument Lists for CALL or LINK 


Communication between modular sections of programming is normally 
effected through an argument list in standard format. Such a 
list is constructed to pass parameters to a subprogram invoked by 
the standard CALL sequence or LINK supervisor call. 


The format is as follows: 
| | |. | 


| Address of Arg (1) | | 1 . Address of Arg (Last) | 


| | {os 
0 4 
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Arg(1) through Arg(Last) are four-byte address values pointing to 
the locations of the actual arguments. The high-order bit of the 
last four-byte area should be set to one to indicate the end of 
the list. Exceptionally, the arguments themselves may be placed 
in the list in place of their addresses. Register R1 is loaded 
to address this list before control is passed to the receiving 
routine. Before initially invoking a program, the program 
initiator (command processor) will set register R1 to binary 
zeroes to indicate that no parameter list is being passed to the 
program. 


Note that a user program may return result values in an argument 
list only if it can be guaranteed that the argument list is in 
the user's modifiable area. 


Zelvked Use of Program Level Parameters 


System conventions for communication between the user's program 
interface (i.e., the command language) and the invoked programs 
are not compatible with the use of standard argument lists. To 
be runnable from the command language, programs must access all 
run-time parameters using the GETPARM SVC. The GETPARM facility 
is used to access run-time parameters in groups of 
keyword-identified values which are interpreted as: 


(1) Run-time device or file assignments, 
(2) Batch oriented run-time option lists, or 
(3) Interaction oriented program command data. 


Programs which require a more flexible level of interaction than 
that provided by GETPARM should access the user workstation using 
the standard data management facilities. 


Parameters requested using GETPARM are usually accessed through 
direct interaction at the user workstation. Alternatively, these 
parameters can be prespecified within procedures using the 
parameter specification statement. In addition, the PUTPARM 
macroinstruction is available to allow a program to. supply 
parameters which are then available through GETPARM to the next 
subprogram LINKed to by this program. 


2.1.1.5.1 Run-Time Device and File Assignment 


Parameter groups solicited by the OPEN routine are used to assign 
actual devices or files to the internal filenames used within 
programs for data transfer. All action related to device/file 
allocation, file lookup, and control block generation is 
performed by OPEN. OPEN uses a number of parameters which must 
be specified by the union of information supplied in the User 
File Block (the only explicit OPEN parameter) and the information 
obtained using GETPARM. The User File Block is compiled into the 
user's program. 
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Some of these parameters are suppliable only in the User File 
Block (UFB). The other parameters are solicited using the 
GETPARM facility with all solicited parameters defaultable to 
values which can be supplied in the UFB. GETPARM enables the 
user (or the command language) to modify the default values 
specified; thus the GETPARM supplied values override  UFB 
information. 


2.1.1.5.2 Default File Specifications 


Default information for the specification of actual files at 
run-time can be placed in the UFB anytime before a file is 
OPENed. This facility should be used to minimize the amount of 
information which must be acquired from the _ user. Information 
Which can be defaulted includes File Location Information and 
File Size. 


The disk space requirements of all output files (including 
‘print’ files) should be specified in the UFB if possible. In 
general, the size of an output file is related in some manner to 
the size of an input file. Input file size is available in the 
UFB for any OPEN input file located on a disk device. Thus, when 
input files can be OPENed first, this size information may be 
used to calculate default space requirements to be placed in the 
output file UFB. 


All information necessary to specify work files should be 
presupplied in the UFB or elsewhere. Space requirements may be 
developed in the manner described for output files. File 
location information, consisting of a filename and a _ volume 
designation, should be developed as follows. The volume location 
of the work files can be left blank in the UFB, to be supplied in 
the ETCB by means of a command language 'SET' command. The 
library name for work files is ignored in the UFB before OPEN. 
It is set to a special user work library (associated with the 
logged-on user) by OPEN processing. The default actual filename 
should be formed by using characters '#' or ‘##' as a prefix to a 
maximum four-character name which is unique to the program. OPEN 
will place after the supplied name a four-character suffix 
sufficient to guarantee temporary uniqueness. Work files whose 
names begin with ‘'#' are scratched when closed. Those whose 
names begin with '#' are retained until run termination. 


2.1.1.5.3 Run-Time Specification of Options 


Batch oriented lists of run-time options should be _ solicited 
directly by the programs using the GETPARM facility. By 
convention, the parameter-reference-name OPTIONS should be used 
to identify this type of parameter group. Also by convention, 
users of this facility are asked to specify reasonable defaults 
for all keywords specified. 
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2.1.1.5.4 Run-Time Command Interaction 


Programs which are inherently interactive may be able to use 
GETPARM to solicit user directives and associated parameters. 
Each format presented to the user must be labeled with a 
parameter-reference-name. The programs using this facility can 
be invoked and directed from procedures. 


2.1.1.5.5 Standard Parameter-Reference-Names 


The parameter-reference-names (PRNAMEs) used to identify file 
specifications and other parameter groups solicited through 
GETPARM should be chosen to assist the user in easy 
identification of parameter function. Within groups of related 
programs, naming conventions should be established to enhance 
recognition and predictability. 


Standard PRNAMEs will be assigned for system utility programs and 
compilers. The PRNAMEs which have been assigned to date are the 
following: 


INPUT - The basic input file (if only one). 
INPUT1-INPUT (n) - Multiple input files used for 
equivalent purposes. 

OUTPUT - The basic output file. 

LIBRARY ~ A library used for input purposes. 

WORK - An I/0 file used for temporary storage 
(if only one). 

WORK1-WORK (n) - I/O files used for temporary storage. 

OPTIONS - The batch oriented option list used to 
define run-time parameters. 

DISPLAY - The user's workstation. 

PRINT - An output file containing data to be 
printed. 
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2eie2 Supervisor Call Routines 


Routines are entered by SVC instructions to accomplish functions 
which require: 


- Modification of the system area of memory, which is 
normally protected from the user, or 


- Execution of privileged instructions, or 


. Intimate knowledge of the operating system's 
organization, 


and which are not accomplished by non-supervisor-call coding in 
dedicated system tasks such as the paging task. Among these 
functions are: 


. Initiation of physical I/O requests. 


. Opening and closing files, including allocation and 
construction of Open File Blocks. 


. Synchronizing tasks through semaphores. 


. Performing service functions for use by other 
supervisor call routines (such as allocating system 
area memory space for control blocks). 


The system programmer should note that the special ‘paging task' 
cannot in the current implementation issue SVC instructions. 


Supervisor call routines accept parameters on the top of the 
stack. The lowest parameter address is at displacement 72 
(decimal) from the stack top pointer on entry. They are entered 
by means of the SVC instruction, which establishes a new save 
area on the task's system stack as shown in Figure 2.3. These 
routines may extend the stack in the user's modifiable area by 
PUSHing items onto it. They need not POP all these items off 
again before returning. Supervisor call routines should exit by 
issuing an SVCX instruction, which restores all registers and the 
Program Control Word from the user's stack and sets the stack top 
pointer (register 15) to the address value in the register 
specified in the R1 field of the SVCX instruction. 
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2.1.3 


System Dialogue and Workstation Use 


The workstation of the Wang 2200VS System must share the duties 


of: 


(1) the primary data-entry and display device used in a 


program 


(2) a system console device for presentation of and 


response to system messages, which may be: 
(a) solicited (e.g., responses to commands) 


(b) unsolicited (e.g., volume mounting requests, device 
error information, etc.) 


Special conventions and protocol are necessary to meet. the 
requirements of these multiple uses: 


(1) 


(2) 


(3) 


(4) 


Supervisor call routines and unprivileged system code 
(such as data management routines) must use the CANCEL 
or GETPARM supervisor calls to send messages to. the 
workstation. 


Messages must be in the format specified in the 
descriptions of CANCEL and GETPARM in Chapter 6 of this 
document. 


Messages relating to background program runs (programs 
running without an associated workstation) will be sent 
to the system console device. 


When GETPARM processing is entered, the workstation 
screen, its resident buffer contents, its status 
(keyboard locked or unlocked, ‘attentions’ received, 
etc.) and its tab settings are saved. Before resuming 
user program processing, this screen and status are 
restored. This saving and restoring also occurs when 
the 'Help Processor’ is entered as a result of the user 
striking the HELP key on his workstation. 
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2.1.4 Error Handling 


There are several classes of errors which the operating system 
may encounter, and which require differing responses: 


. Program exceptions in user programs 


. Program exceptions and other uncorrectable errors in 
system routines 


; Invalid parameters passed to system routines 
. 1/0 errors 


(1) Program exceptions in users' programs are of concern to the 
operating system's program check interrupt handler, which 
passes control to the HELP processor or to a 
program-specified exception handler. 


(2) Program exceptions and other uncorrectable errors in system 
routines may result in message display by the CANCEL SVC 
(disallowing continuation of the program's processing) if 
their cause can be traced to the user's program (as may be 
the case with certain exceptions in supervisor call 
routines). Otherwise they must be considered probable 
system failures, and result in an orderly system halt. 


(3) If a system routine receives invalid parameters, it should 
be able to detect this during initial validation of the 
parameters and before using them for further processing. 
It then responds as in (2) above. 


(4) I/O errors may be of three kinds: 

. Soft errors, signifying that an I/O operation was 
successfully completed after retry by the separate I/0 
Processor (IOP). 

. Hard errors, signifying failure of an I/O operation 
(including memory parity errors detected on an 1/0 


operation) . 


. Logical file processing errors which do not reflect any 
errors occurring during an actual I/O operation. 
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Soft error indications are passed to the CHECK supervisor 
call routine (in the I/0 Status Word) to be logged in a system 
error logging file, and otherwise ignored. Hard errors are 
passed in the same way. The task responsible for the I/O either 
issues a CHECK to wait for completion of the associated I/0 
request or will make reference to the file again (by another Data 
Management Function request, a CLOSE, or an implied CLOSE on 
program termination). At that time, error indications are 
examined and the user's I/O error routine entered for hard errors 
if such a routine has been provided. In the absence of such a 
routine, the user's program may be abnormally terminated at the 
discretion of the Data Management routines, through issuance of a 
CANCEL supervisor call. Memory parity errors detected by 1/0 
processors are logged just like other I/O errors. 


The user's I/0 error processing routine and his end-of-data and 
invalid-key-condition routine are specified in tthe User File 
Block (see Chapter 5). These routines are entered after 
interpretation of the I/0 Status Word (IOSW) by the Data 
Management System routines. The I/O error routine is entered on 
logical file processing errors (such as invalid function 
requests) as well as on actual hard I/O errors. 


These routines are entered from the unprivileged data management 
routines as if the data management function had returned 
normally, but with the return address modified to be one of these 
addresses from the UFB. All register contents are restored 
except register zero, which is set to contain the normal return 
address from the function (next instruction after the JSCI 
instruction by which the function was initiated). Register 1 
continues to address the User File Block, which may be used to 
determine the nature of the unusual occurrence, as indicated in 
fields UFBFS1 and UFBFS2 of this block (file status bytes). The 
I/O error processing routine is entered for all unusual 
conditions, including end-of-data and invalid-key conditions, in 
the absence of a separate routine. The end-of-data and 
invalid-key routine address, when supplied, overrides the I/0 
error routine in the case of end-of-data and invalid-key 
conditions. 


These routines are entered with the same addressability and 
protection status as for any other part of the user's program. 
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2.2 DOCUMENTATION 


2.2.1 Naming Conventions 


No name in the system may be over sixteen characters long. Thus 
no control block label may be over fifteen characters long (to 
allow for suffixing - see Appendix A). No external name 
(appearing in the Linkage Section of an object module) may be 
over eight characters long. 


Uniform conventions for names of external entities (which may be 
referred to in other parts of the system) are useful in order to 
prevent conflicts of names as well as to make documentation more 
intelligible. The standards to be maintained by programmers of 
operating system routines are described in the following 
paragraphs. 


2.2.1.1 External Names in Code 


Names which appear as entry names in object text must be unique 
across the system. To insure this, a unique prefix for external 
names is assigned to each separately assembled or compiled 
portion of operating system text. 


1. The first character of a name identifies WANG-supplied 
programs: 


W - WANG supplied 


2. The second character of a name identifies the major 
area of system code to which it belongs: 


- Central supervisor 

~ Supervisor call routines 

- Initialization 

- Command and HELP processing 
~ Data management 

- System service tasks 

- Operating system utilities 
~ Stand-alone utilities 

- Linkage editors 

Assembler 

- COBOL 


- Text editors 

- Other independent components 
- FORTRAN 

- Data base 

- Word Processing 

~ File management utilities 


QeEaeaxr mH Mwnwnarpreacvw Ve SZ aan 
1 
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3. 


The third (and, for SVC routines, fourth) character 


identifies 
code falls: 


(S) 1 
2 

3 

4 

5 

6 

7 

8-end 

(Vv) 00-end 
(N) 1 
2 

(M) 0O-end 
(D) O0-end 
(P) 1 
2 

(U) 1 
2 

3 

4 

5 

6-end 

(T) 1 
2 

3 

4 

5 

6 

7 

8 

9 

A 

B 

C 

D 

E 

F 

G 

H 

I-end 


the specific functional area into which the 


Task scheduler 

Clock interrupt handler 

I/O interrupt handler 

Program check interrupt handler 
SIO routine 

Pager 

Page, SVC, or I/O tracing 
Additional service subroutines 


SVC routines by SVC number 


System initialize (IPL) 
Task reinitialize routines 


Command and HELP processing 


Data management vectored routines and 
subroutines 


Operator's console program 
File sharing handler 


Disk volume analyze and label 
Display and alter disk 

Copy tape to disk 

Copy file, library, or volume 

Copy tape to disk (tape bootstrap) 
Assigned as needed 


On-line disk volume initialize 
Display file 

Disk copy 

Tape copy 

Print listing file 

List Volume Table of Contents 
Sort 

Print debugging dump from diskette 
Copy unloaded IBM 08/370 PDS 
Patch file 

System procedure interpreter 
COPY2200 

FLOPYDUP 

BACKUP 

VERIFY 

TAPEINIT 

SECURITY 

Assigned as needed 
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(L) l-end Linkage editors (binders) 
(A) 1-end Assemblers 


(C) 1-end COBOL compiler and COBOL symbolic debugging 


(R) 1 RPG compiler 
(E) 1 COBOL and Assembler Language source text 
editor 


2-end Assigned as needed 
(I) 1-end Other independent components 


(G) 0 Common file management subroutines 
1 CONTROL 

2 DATENTRY 

3 REPORT 

4 INQUIRY 

5 CONDENSE 

6 


KEYENTRY 


(Programming in categories U, T, L, A, C, R, E and 
I would not normally contain entry names. These 
categories are included for completeness and to 
provide a noncompulsory standard for coding.) 


4. Four or five characters uniquely identify the name. 
Some examples might be: 


WS1SCHD 
WS3STIM 
WVO4LINK 
WD8WRIT 


2.2.1.2 Names in System Data Structures 


These are external symbols in the sense that more than one data 
structure description (control block definition) may be included 
in an assembly or compilation, and therefore, names must be 
unique across all these descriptions. 


Each system data structure has a_ three-character to 
five-character name, as defined in Chapter 5 of this document. 
These names and any names formed by using these characters as a 
prefix are considered reserved names in assemblies of system 
code. Each label of a field within a system data structure 
definition must begin with these characters. 
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2.2.2 Macroinstruction Descriptions 


Descriptions of all supervisor service macroinstructions, in 
alphabetic order by name, are collected in Chapter 4 of this 
document. Each description includes: 


1. A functional title for the macroinstruction. 


2. A syntax specification on the first line of the 
description, with optional operands displayed in 
brackets. 


3. A specification of the restrictions placed on the use 
of the macroinstruction, such as ‘for use by disk 
management support only’ or ‘register Rl must contain 
the active Task Control Block's address when this 
macroinstruction is executed', or 'for use by disabled 
routines only’. 


4. A general functional description. This should describe 
what the macroinstruction accomplishes, without 
describing its internal workings in detail. 


5. Descriptions of each operand and its effect on the 
function of the macroinstruction. \ 


6. At least one example of code generated by this 
macroinstruction. 


Examples of the format required may be found in Chapter 4. 


7 ey es Data Layouts and Descriptions 


The format for describing system data structures is presented by 
example in Chapter 5 of this document. Note that the type of 
data in each named field of a data structure or control block is 
specified by the corresponding assembly language type designation 
and length (e.g., BL1, AL3, etc.), and that a brief description 
of the function of each field is included. 
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2.2.4 Supervisor Call (SVC) Routine Descriptions 


Descriptions of all supervisor call routines are provided, in SVC 
number order, in Chapter 6 of this document. Each description 
includes: 

1. SVC number and name. 


2. A description of all direct and indirect inputs to the 
routine. 


3. A description of all outputs (including ‘'side-effects'). 


4, A functional description of the processing performed by 
the routine. 
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CHAPTER 3: SYSTEM DESCRIPTION 


3.1 VIRTUAL MEMORY 


The user is not aware of the specific functions involved in 
providing him with a virtual main storage larger than the 
physical main storage of the hardware. However, an understanding 
of the mechanism involved will aid in understanding’ the 
protection mechanism and will be useful to the programmer who 
feels he must understand the Operating System's internals. Also, 
a general awareness of how paging is carried out may help any 
programmer write more efficient code for the machine. 


3.1.1 Relation of Virtual Memory to Physical Memory 


The physical main memory of the Wang 2200VS is limited to a 
maximum of 512K (K=1024) bytes. A computer instruction can, 
however, develop an address which refers to any of 16,777,216 
(16,384K) memory locations. Thus a programmer could write a 
program which would execute in Wang 2200VS' physical memory only 
if a much larger memory were available. Being able to execute 
such a program means considerable savings in coding time, since 
the programmer then need not segment a large program into 
overlays. A similar situation arises with respect to the areas 
containing user-modifiable data. If the programmer must design 
for a system in which these areas are severely limited, he must 
make explicit use of secondary storage (disk, tape, etc.) to 
temporarily save intermediate results. This may result in more 
coding time, a more complex program, and considerable 
inefficiency. 


The foregoing problems can be alleviated if the Operating System 
manages main memory in such a way that the user appears to have 
one or more large addressable areas of memory available. Under 
such a scheme, the Operating System overlays portions of the 
user's program and data with other portions as necessary, 
according to some rules which are sufficiently close to optimal 
to allow the program to proceed at nearly the speed at which it 
would execute if all of the program and all the work area for 
data were in main memory constantly. The memory which the user's 


program addresses is then referred to as a ‘virtual memory‘ and 
the actual main memory as the 'physical memory’. In the Wang 
2200VS, one user's virtual memory includes a reentrant program 
segment of up to 512K bytes, a modifiable segment of up to 512K 
bytes, and a system code and data segment of up to 256K bytes. 
The virtual memory exists in complete form only on a secondary 
storage device (disk). 


3.1.2 Address Translation, Pages and Page Faults 


It is the relationship or ‘mapping’ between a large virtual 
memory and a smaller physical memory which the paging management 
routines of the Operating System provide. This is done as 
follows: 


The physical memory is partitioned into ‘page frames' of 2048 
(2K) bytes each. (A 128K system would have 64 page frames.) 
Certain of these page frames are dedicated to contain Operating 
System routines and data which must be resident at all times. 
The other page frames may contain parts of any other programs or 
data. As far as an executing program is concerned, it may 
address any one of sixteen large contiguous areas of storage (up 
to 512 pages each) referred to as ‘segments’. The particular 
segment addressed is selected by the four high-order bits of a 
24-bit address. The user program code is in segment one, the 
user modifiable data area in segment two, and supervisory 
routines and data in segment zero. References to segments’ three 
through fifteen are invalid, and are treated as program errors. 
Actually, the hardware uses these four bits to select a ‘page 
table', each item of which in essence addresses a page frame in 
the physical main memory. The nine bits of the original 
(‘untranslated') address following the segment selection bits are 
used to select one of up to 256 page table items within a page 
table, and thereby to select a physical page. The last eleven 
bits of the original address are then used to address a byte 
location within this page. The resulting addressed location is 
referred to as the 'translated' address. Note that although up 
to 256 page table items may be addressed within a page table, 
there is a maximum of 64 page frames available in the physical 
memory of the 128K system hypothesized above. Some page table 
items are therefore marked with a special indication that the 
referenced page is missing from physical memory. The hardware, 
finding this indication set during an address 'translation', 
effects a particular type of program check interruption known as 
a 'page fault’, and supplies to the program interrupt service 
routine the segment and page numbers of the missing page. A task 
initiated by this interrupt service routine, the ‘paging task’, 
attempts to locate a page frame the contents of which may be 
replaced with the required page from a disk file. When a page 
frame containing a replaceable page has been selected, the paging 
task reserves this page by indicating that it is in use for 
page-in or page-out, and initiates the page-in, or page-out 
followed by page-in, operations. The task which needs the page 
is forced to wait on a queue of tasks attached to the page frame 
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being used for the paging operation, and will be reactivated 
after the page-in operation completes and the paging task has 
updated the page table to allow normal addressability of the page. 


3.1.3 User Program Efficiency and Paging 


Designing a program for a virtual memory environment requires a 
new outlook toward program and data organization. Although the 
user is freed from the onerous task of managing a small physical 
storage by overlay or other manual segmentation techniques, he 
cannot ignore the issue of program organization. A major aim of 
the programmer should be to increase the locality of reference of 
his program's code. That is, he should avoid referencing many 
pages of code or data within a short span of program execution. 
In this way he will reduce the likelihood of many page faults 
occurring. One might also say, as a general rule, that it pays 
to spend processor time to save space; the notion of a tradeoff 
between the amount of storage area required and the speed at 
Which a program executes is not, however, as accurate ina 
virtual memory system as in most previous systems. 


3.2 SUPERVISORY FUNCTIONS 


The following paragraphs describe briefly the most important 
functions of the central supervisor. System programmers 
requiring more detailed information should consult program logic 
documents. 


362k Task Scheduling and Timing 


The operating system supports one or more tasks corresponding to 
users' programs in progress, in addition to a paging task. 
Determination of which task is to have control of the processor 
at any time is made by the scheduler routine, which gains control: 


(1) when a task WAITs on a semaphore (associated with an 
event which is expected to occur but has not yet 
occurred) . 


(2) when a task becomes ready as a result of a SEND on a 
semaphore. (This is associated with the occurrence of 
an event.) 


(3) when an interrupt has occurred, and preliminary 
processing of the interrupt has completed (e.g., on 
exit from the I/O interrupt service routine or clock 
interrupt service routine). 


(4) when ‘System Must Complete’ state is exited, and a 


workstation HELP key had been received while in ‘System 
Must Complete' state. 
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The scheduler determines the highest-priority ready task, sets a 
timer expiration value to insure that this task cannot monopolize 
use of the processor at the expense of other tasks (most 
obviously by looping), and loads the control registers, page 
tables, general registers, floating-point registers, and _ the 
program control word (PCW) associated with the task to be given 
control. This task is allowed to run until one of (1) through 
(4) above occurs. 


3.2.2 WAIT and SEND Primitives 


When a task is not available for scheduling, it is said to be 
"blocked'. Blocking and wumnblocking of tasks is accomplished by 
the WAIT and SEND primitives which execute DSEM or  ISEM 
instructions, respectively. The functions are as follows: 


(1) WAIT - This function is always performed by a special 
operating system WAIT routine. An addressed 
semaphore's count field is decremented. If the result 
is zero or greater, control returns to the invoking 
program. If the result is less than zero, the 
currently active (invoking) task is blocked and control 
is passed to the scheduler. User programs must use the 
CHECK SVC routine to gain access to this facility. 


(2) Multiple WAIT - This function is similar in effect to 
WAIT, but allows a task to await the occurrence of 
one-out-of-several specified events, each represented 
by a semaphore. 


(3) SEND - This function is performed by a special 
operating system SEND routine as requested by an SVC 
call or special branch-type entry for interrupt 
routines. The SEND routine increments an addressed 
semaphore's count field (by executing an ISEM 
instruction). If the result is less than or equal to 
zero, a task has been unblocked by this instruction, 
and the routine passes control to the scheduler. If 
the result is greater than zero (no task unblocked) , 
control is simply returned to the invoker. (Interrupt 
routines either pass control to the scheduler or to the 
interrupted task at some time after a SEND branch type 
entry.) 


Users' programs do not have the ability to modify semaphores 
except by invoking the CHECK routine through supervisor call. 
After checking the request for validity, CHECK enters the WAIT 
routine. All semaphores are in protected memory locations. 


3.2.3 Intertask Message Primitives 


The XMIT primitive allows a task to queue a message of up to 251 
bytes for transmission to another task. The WAIT primitive 
(through the CHECK MESSAGE macroinstruction) allows a task to 
wait for receipt of such a message. 
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3.264 Supervisor Call Interruptions 


Section 2.1.2 above describes the functions performed by SVC 
routines. The reader may wish to refer to this section and _ to 
Figure 2-3. 


3.2.5 I/O Initiation 


Issuance of the actual SIO instruction to initiate either paging 
or normal I/O is localized in the system's Start I/O routine. No 
other system components issue SIO instructions. The Start I/0 
routine is passed a Request Element which describes the I/0 
operation to be performed and points to a semaphore on which the 
I/O interrupt service routine will perform a SEND when the 
operation is complete. The Start I/O routine is called by the 
XIO supervisor call routine and the paging task. The Start I/0 
routine itself queues the Request Element to the proper device's 
physical request queue, and then attempts to address the first 
element on this queue and perform its requested 1/0 operation. 
If the device is busy, this step is bypassed (I/O will be started 
later, when the current I/O completes). 


3.2.6 I/O Interruptions 


The I/O interrupt service routine gains control on an I/0 
interruption. As well as ‘unfixing' the I/O area (removing the 
page or pages it occupies from ‘temporarily resident in memory' 
status) on I/0 completions other than page faults, and saving all 
necessary status of the interrupted task, it locates the I/0 
Request Element associated with the operation which has 
completed, performs a SEND operation on the semaphore addressed 
by this element, and dequeues the element. It then calls. the 
system's Start I/0 routine to initiate I/O for any requests which 
may be pending. Exit is then made to the interrupted task, or to 
the scheduler to restore the status of another task and dispatch 
it. Interruptions indicating 'I/O processor now ready’ cause the 
I/O interrupt service routine to attempt to initiate operations 
on all affected devices (those on the same I/O processor) which 
have request elements queued for servicing. ‘Attention' 
interruptions are also processed by the I/0 interrupt service 
routine, which performs special device-dependent processing of 
‘attention’ interruptions from workstations. 


3.2.7 Clock Interruptions 


The system's clock interrupt handler receives control when a 
clock interruption occurs. If a task is active and _ the 
interruption indicates the end of its time slice, it is marked 
‘timeslice expired', placed last on the low priority scheduling 
queue, and the scheduler is entered to schedule another task, or 
the same task again if no other is ready. If the interruption 
Signals the expiration of a program-specified timing interval, 
the clock interrupt handler performs a SEND operation on the 
semaphore in the appropriate interval timing element (TQEL), and 
then exits through the scheduler to schedule a task which may 
have been unblocked by this SEND operation. If the interruption 
signals a midnight crossing, the system date is updated and the 
time-of-day reset. 


3.2.8 Program Interruptions (Other Than Page Faults) 


The program interrupt handler entered on a program interruption 
will force entry to a program exception exit routine if one has 
been specified for this type of exception, and otherwise to the 
system's HELP processor. This will allow the user to request use 
of a debugging routine, or to simply terminate the program. 


3.2.9 Program Normal Termination 


Normal termination processing is entered on RETURN from a program 
originally entered from the command processor, or on execution of 
an UNLINK supervisor call by such a program. The memory occupied 
by the program is made available for other use. Open files are 
closed and any logging information is written. 


3.2.10 Program Abnormal Termination 


Abnormal termination (processing "cancellation") may occur in 
response to one of the following: 


(1) The user requested abnormal termination in response to 
Help Processor prompting, the user having obtained the 
services of the Help Processor by striking the 
Workstation's HELP Key. 


(2) The program issued a CANCEL supervisor call or entered 
the Debug Processor by virtue of a program check 
(without having issued a PCEXIT supervisor call) and 
the user requested abnormal termination in response to 
Debug Processor prompting. 


(3) The program issued a CANCEL supervisor call or program 
checked (without having issued a PCEXIT supervisor 
call) and the program itself had previously issued a 
CEXIT supervisor call with the NODEBUG or DUMP option. 
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The abnormal termination processor (Cancel Command Processor) 
will attempt to close files open to the program being 
terminated. Assuming that the program has not issued a CEXIT 
supervisor call specifying an address of a user "cancel exit 
routine," the program is removed from execution and control is 
passed to the command processor to allow another program to be 
initiated. 


Programmed interception and analysis of abnormal termination 
conditions is available to the user program via the CEXIT 
Supervisor call. The "cancel exit" parameter of the supervisor 
call specifies the address of a routine in the user's program 
that is to receive control in the event of an abnormal 
termination condition. 


Upon entry to a user program's “cancel exit routine,"' the program 
name, PCW, general registers, and cancellation codes and message 
are provided on the system stack for subsequent analysis. The 
floating point registers reflect their value at the time of the 
abnormal termination condition. The program may take any desired 
corrective action and subsequently elect to either continue 
processing normally or terminate. (See "CEXIT Supervisor Call" 
for additional details.) 


S3c2e11 Program Initiation 


The initiation of user programs is a function of the system's 
Command Processor and Procedure Interpreter, which issue LINK 
SVCs to initiate programs. 


3.2.12 Microcode Loading 


When an IOSW is received that has bits PP (peripheral processor 
code missing) or DP (device code missing) set, the I/O interrupt 
routine marks the UCB ‘not busy' (UCBSTATBUSY reset) and 'no 
code' (UCBSTATNOCODE set), increments the 1/0 completion 
semaphore, and leaves the IORE on the I/O queue with the pages 
used for the I/0 operation fixed. IOREREQFIVRQ is set to 
simulate an IVRQ interrupt. SIOs are blocked by UCBSTATNOCODE. 


The task waiting on the I/0 is restarted, and enters CHECK 
completion code. CHECK finds IOREREQFIVRQ set and enters 
‘intervention-required' processing. It then finds PP or DP set 
in the IOSW, and calls SVC LOADCODE to load the appropriate 
microcode. If LOADCODE is successful, it will have marked the 
UCB ‘code loaded' (UCBSTATNOCODE reset), and restarted the 1/0 
Operation. CHECK then waits for I/0 completion. 


If LOADCODE failed, CHECK calls HALTIO to remove the _ 1/0 
operation from the 1/0 queue and unfix the data area. CHECK then 
reports the IOSW as an error completion; if the device is a 
Workstation, it marks the device 'turned off' (UCBSTATNOTOP set) 
to block I/O operations until the Workstation is turned on. When 
the Workstation is turned on , the unsolicited interrupt will 
mark the device 'turned on' (UCBSTATNOTOP reset) and ‘loaded’ 
(UCBSTATNOCODE reset) to unblock I/0 operations. The next I/0 
operation to the device will find the microcode not loaded and 
reload it. 


Receiving an I/O completion interrupt with DP and PP both set may 
indicate that the device configuration table is missing. This is 
handled like an interrupt with 'DP' or ‘PP’ set. 


3.2.13 Logoff 


Logoff is defined as the termination of a user's current session 
with the computer. It may be invoked in either of the following 
manners: 


(1) The user may request Logoff voluntarily by keying the 
appropriate initiator function key. In this particular 
case, the Logoff Processor permits the user to "escape" 
from Logoff by pressing the HELP key. 


(2) The program may issue a LOGOFF supervisor call in 
response either to an interactive user request or any 
other specified conditions detected by programming. 
Such a logoff is essentially handled as a program 
cancellation, without entry to the Debug Processor, 
unlinking all link levels, bypassing the Initiator, 
logging off the current user, and displaying the Logon 
Processor screen on the workstation. A message is 
displayed indicating that the previous program was 
logged off by "program request."' Note: LOGOFF 
supervisor calls may be intercepted by a program's 
active “cancel exit routine," distinguished by message 
0001 issued by SVC43. 


The Logoff Processor, in both the above cases, prompts the user 
for a response for each volume mounted by that user for exclusive 
use. The user is provided with a choice of changing the mount 
status from "exclusive" to “shared" or, where appropriate, 
dismounting the volume. 


3.3 DATA MANAGEMENT FUNCTIONS 


A general introduction to the implementation of Wang 2200VS data 
management follows. The system primitive functions provided to 
aid in processing I/0 requests are explained briefly in Section 
3.3.2. For more detailed information, consult the appropriate 
program logic documents. 
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3.3.1 Top Level Data Management Function Support 


Entry to system code for processing data management requests. is 
by indirect branch to routine addresses in a file's User File 
Block. Most data management code is executed in unprivileged 
mode as an extension of a user's program. 


3.3.2 Data Management Support SVC's 


Primitive I/0 services are provided through supervisor call 
routines which are to be used by the data management system in 
the process of servicing READ, REWRITE, WRITE, DELETE, START and 
other requests. The XIO and CHECK services may also be used in 
nonstandard I/0 programming. 


3.3.2.1  XIO 


The XIO service provides intermediate~level I/O initiation 
support. When called by SVC from data management programs, it 
converts block numbers in a disk file to disk addresses, 
validates that disk addresses lie within proper extents, 
translates virtual data addresses (in I/0 Command Words) to 
physical addresses, makes the required pages of virtual memory 
temporarily resident (‘short-term  fixed'), and calls the 
supervisor's Start I/0 routine to initiate the I/O operation. 


3.3.2.2 ALEX 


The ALEX service is requested by data management routines when a 
primary or secondary extent on disk is exhausted and it is 
necessary to either allocate another extent or, failing that, to 
terminate processing. 


3.3.2.3 CHECK 


The CHECK service is used by data management routines to suspend 
the operation of the issuing task until an I/O operation is 
signalled complete (by a SEND function in the I/O interrupt 
service routine). The user-level data management routines must 
use CHECK, since they are not allowed direct use of the WAIT 
primitive function. Basically, the difference between these 
functions is that CHECK will insure that a valid Open File Block 
address has been passed to it, while WAIT cannot validate the 
semaphore address which it receives. CHECK will also handle 1/0 
error logging and detection of ‘intervention required' conditions 
at the device. (See the CHECK supervisor call and 
macroinstruction descriptions for additional functions of CHECK, 
including its role in interval timing support and inter-task 
message passing.) 


3.4 DISK STORAGE DESCRIPTION 


Disk volumes on the Wang 2200VS system are divided into logical 
256-byte sectors, numbered from zero. Actual disk sectorization 
is into 256-to-2048-byte sectors, depending on the device type. 
Although each actual sector may be addressed by I/O command, the 
operating system XIO routine and paging routines always address 
2048-byte areas referred to here as 'blocks' of disk storage, 
which begin on logical sector addresses which are multiples of 
eight. Files on such a volume are recorded in one or more 
contiguous areas (‘extents'). Each extent spans one or more 
consecutively-numbered blocks. The presence of a_e file is 
indicated in a volume table of contents which is organized to 
allow a hierarchical naming scheme with one level of 
qualification. This structure is located through the volume 
label. All these items are discussed in the following paragraphs. 


3.4.1 Volume Label 


The volume label occupies sector 1 (the second sector) of any 
disk volume. It contains the name of the volume (volume serial 
number), the location (extent descriptions) of the volume's table 
of contents, and other descriptive information defining the size 
and physical organization of the volume. 


3.4.2 Extent Organization 


Each block on a volume, with the exception of the first block 
(sectors 0 to 7) and the blocks containing the volume table of 
contents, is part of an ‘extent’ (defined contiguous area) of 
either free space or file space. Extents of free space are 
recorded in available space records of the volume table of 
contents. Extents of file space are recorded in File Descriptor 
Records (FDRs) in the volume table of contents, where each FDR is 
associated with a particular file. The initial FDRs for files 
are referred to as Type 1 FDRs. FDRs describing additional areas 
occupied by a file are referred to as Type 2 FDRs. 


When a file is initially allocated space, an attempt is made to 
acquire a single extent of sufficient size on the specified 
volume. If such an extent is not available, up to 3 extents may 
be allocated. 


When a file is enlarged so that it exceeds the capacity of 
extents previously allocated for it, the system allocates an 
additional extent. This may require that an additional FDR be 
allocated to contain the additional extent information (a Type 2 
FDR). A file may encompass a maximum of 13 extents (described in 
one FDR1 record and one FDR2 record). 
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3.4.3 Volume Table of Contents 


The volume table of contents on a disk volume has blocks 
(8-sector areas) of four types. There are available space blocks 
Which record where free blocks are on the volume, high-level 
index blocks which contain file name qualifiers and low-level 
index block numbers, low-level index blocks which contain file 
mames and file descriptor block numbers and = file descriptor 
blocks containing File Descriptor Records which contain attribute 
specifications for particular files, including the location of 
the file on the volume and the extents allocated for it. 


The first block of the volume table of contents is an available 
space block. Any search for available space on the volume (for a 
newWly-allocated file or an additional extent) begins by searching 
this block, followed by its chained blocks, for a sufficiently 
large area of space. 


The second block of the volume table of contents is an index 
block. It is the first block of the ‘top-level' index. 
Additional top-level index blocks may be chained from this 
block. This top-level index contains pointers to lower-level 
index blocks, which in turn contain pointers to File Descriptor 
Records. The name of a lower-level index, as recorded in each of 
its index records, is used as a file name qualifier to define a 
complete file name or ‘path name'. For example 'DIRECTB.FILEA' 
could be the name of a file whose File Descriptor Record is 
located by a pointer in an index item containing 'FILEA‘, where 
this item is in a lower-level index record whose name is 
"DIRECTB'. It is useful to refer to the file as member ‘FILEA' 
in library ‘DIRECTB'. The first high-level index block also 
contains three linked-list head pointers, which are used to 
maintain chains of 


(1) available blocks, 

(2) blocks containing available low-level index records, and 

(3) blocks containing available File Descriptor Record 
areas. 


The third block of the volume table of contents is reserved for 
use as the first lower-level index block. Each such block may 
contain all or part of up to four ‘libraries’ as described above. 


The fourth block of the volume table of contents is a block 
containing File Descriptor Records. 


The fifth and additional blocks of the volume table of contents 


are used as required for available space blocks, index blocks, or 
file descriptor blocks. 
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CHAPTER 4: SYSTEM MACROINSTRUCTIONS 


4.1 | MACROINSTRUCTIONS AVAILABLE 


This chapter documents the Wang-defined macroinstructions 
available for general programming use. A second set of 
macroinstructions, designed for operating system development and 
support and not intended for general use, are documented in a 
separate manual. 


The available macroinstructions are summarized in the following 
list, arranged by functional category. The remainder of this 
chapter consists of individual discussions of all general-purpose 
macros, arranged alphabetically by keyword. 


A. User program linkage 
CALL, RETURN, LINK 
Bl. User-level 1/0 
OPEN, CLOSE, READ, REWRITE, WRITE, DELETE, START, 


RENAME, SCRATCH,. UFBGEN, BCIGEN, AXDGEN, MOUNT, 
DISMOUNT, READFDR, TCOPTION 


B2. Data management routine use 


X10, GETBUF, FREEBUF, CHECK, ALEX, HALTIO 


C. Synchronization and resource control 


WAIT, SEND, SEIZE/RELEASE (Not available for general 
programming use) 


D. Resident block management 


GETMEM, FREEMEM (Not available for general programming 
use) 


Timing 

TIME, SETIME, RESETIME, CHECK 

Program termination and debugging 

CANCEL, (RETURN) 

Workstation display, message log 

GETPARM, KEYLIST, MSGLIST, FMTLIST, PUTPARM 


Program structuring and control 


REGS, EXTRACT, PCEXIT, SET 
LOW (Not available for general programming use) 


Intertask communication 


XMIT, CHECK, CREATE, DESTROY 


Allocate Extent 


Syntax 


[label] ALEX OFB=(register) 


Restrictions 


For use by Data Management System routines only. 


Function 


Attempts to allocate an additional extent for the disk file 


whose 


Open File Block (OFB) is addressed. A file has to be 


opened for exclusive use before ALEX is issued. The OFB 


address 


is stacked before issuing the Supervisor Call. On 


completion of the function, the OFB address is removed from 
the stack and a return code word is stacked, as follows: 


- Additional extent allocated 

~ Invalid OFB address or OFB not open for this task; 
no allocation 

~ File in INPUT mode; no allocation 

~ Wrong device class; no allocation 

- Extent limit would be exceeded; no allocation 

- All buffers in use, GETMEM failure; no allocation 

~ Volume full; no allocation 

~ No space in VTOC for FDR2; no allocation 

~ Disk I/0 error; VIOC unreliable 


Operand Description 


OFB= 


The address of an Open File Block for an open disk 
file. It must be presented as a_ register 
specification in parentheses, where the register is 
assumed to contain the OFB address. 


ALEX OFB=(R1) 
PUSH 0,R1 
svc 14 (ALEX) 
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Generate Alternate Index Descriptor Block 


Syntax 


[label] AXDCGEN [MASKSIZE=p1] [,ENTRIES=p2] 


Function 


[,(ORD=p3, KEYPOS=p4, 
KEYSIZE=p5 [,NODUPS] 
{,COMPRESS])] .... 


Generates an alternate index descriptor block (AXD1) to be 
addressed by UFB field UFBALTPTR (ALTAREA operand of UFBGEN 
macroinstruction) . 


Operand Descriptions 


MASKSIZE 


ENTRIES 


Must be 2 or omitted. 


To use the AXD1 for OUTPUT mode processing, 
must equal the number of positional operands 
(in parentheses) which follow. Always must be 
zero, omitted, equal to the number. of 
positional operands, or 0 to 16 if there are no 
positional operands. 


Positional suboperands: 


ORD 


KEYPOS 


KEYSIZE 


NODUPS 


COMPRESS 


Index (1 to 16) defining this alternate index 
structure (access path). Required in all 
supplied positional operands. 

Key position in record. Required. 


Key length. Required. 


Duplicates not allowed if specified for OUTPUT 
mode. Ignored in other modes. 


Key compression if specified for OUTPUT mode. 


Ignored in first version of alternate indexing 
Support. 
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AXDGEN 


Example: 

LAB1 AXDGEN ENTRIES=1 

+LAB1 DC F'0' BL 
DC XL14'0' MASK, UFB, ALTINX, FLAGS 
DC HL1'2' MSIZE 
DC XL41'0' SPARE1, BCB, PMASK, SPARE 

*AXD ENTRY FOR ALTERNATE ACCESS PATH 

DC AL1 (0) XORD 
DC BL1('10000000') FLAGS 
DC H'0' LEVELS 
DC AL2 (0) KEYPOS 
DC AL1 (0) KEYSIZE 
DC XL21'0' HXBLK, NRECS, PTRD, ESPARE 
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Generate a Buffer Pool Control Table 


Syntax 
{label] BCTGEN NBUF=expression 
Function 


Generates a skeleton buffer pool control table for use in 
buffer pooling (UFBGEN macroinstruction, operands POOL and 
BCT). 


Operand Description 


NBUF= An absolute expression must be supplied, which must 
evaluate to an integer not greater than 60. This 
is the number of buffers to be included in the 
buffer pool. 


Example 
LAB1 BCTIGEN NBUF=8 
+LAB1 DS OF 
+ DC AL1 (8) 
+ DC XL19'00' 
+ DC (8) XL28'00' 


Call a 


Syntax 


[label 


Restri 


Subroutine 


[ 
] CALL EPLOC=Entry-address-word | ,PARM={ (register) } 
a | { label } 

| 


| PARMLOC=parm-address-word 


[ 
[ ,COND=number] 
ctions 


A stack, with stack top addressed by general register 15, 
must be available to the CALLer. 


on 


Functi 


Loads the address of a parameter list (if specified) into 
register Rl and branches (conditionally) to the specified 
label or to the address contained in ‘entry-address-word' 
by a JSCI instruction (leaving the return address on the 
stack). The JSCI instruction saves the contents of control 
register 1. The JSCI instruction also stores general 
registers 0 to 14 on the stack and places the address of 
the register 0 save area in control register 1 (as well as 
in the stack pointer, general register 15). The lowest 
address in any current ‘static’ area is (by convention) 
passed in register R14. 


Operand Descriptions 


EPLOC= The address of a word containing the CALLed 
routine's entry point address. This must be 
specified in a form allowable in the D2(X2,B2) 
fields of the RX-type assembler instruction 


format. 
PARM= The address to be passed in register Rl. 
PARMLOC= The address of a word containing the address to 


be passed in R1 (with format as for EPLOC). 


COND= Specifies the condition codes under which the 
routine is to be CALLed. If omitted, 'COND=15' 
is assumed. 


LAB1 CALL PARM=PADDR , EPLOC=ENTRYWRD , COND=8 
+LAB1 LA R1,PADDR 
+ JSCI 8 ,ENTRYWRD 
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J 
| 
| 
| 
| 


[label] CANCEL MSG={ (register) } 
{ address } 


Restrictions 


Must not be issued while in System Must Complete state. 


Function 


To enter the Help Processor for cancellation of the issuing 
program. The message provided is displayed, along with a 
standard CANCEL message. The user may then use the Help 
Processor's debugging facilities to examine the program 
before issuing a CANCEL command to remove it from the 
system. If the CANCEL supervisor call was issued from 
within a user's program, the user may attempt to continue 
processing by modifying the location to receive control and 
invoking the "CONTINUE" command. A program terminated by a 
CANCEL supervisor call from within privileged code cannot 
be continued. 


Operand Description 


MSG= The address of a message to be displayed, contained 
in the specified register, or at the specified 
address. A register specification must _ be 


parenthesized as shown. The message must be in the 
format generated by the MSGLIST macroinstruction. 


LA R5 , LAB2 

LAB1 CANCEL MSG=(R5) 

+LAB1 PUSH 0,R5 

+ Svc 16 (CANCEL) 

LAB2 MSGLIST ‘C001', 'SUPVSR' , "MEMORY POOL 
EXHAUSTED' 

+LAB2 DC CL4'C001' 

+ DC CL6'SUPVSR' 

+ DC AL2 (21) 

+ DC C'MEMORY POOL EXHAUSTED' 


Cancel Exit 


Syntax 


(1) [label] CEXIT CANCEL 


(2) [label] CEXIT SET [,({NODEBUG] [,NOHELP])] 


Function 


CANCEL = 


SET = 


C {DUMP J J 


[ ,AADDRESS={ (register) }] 
[ { expression}] 


[ MESSAGE={ (register) }] 
[ { expression}] 


Negates the effect of any previously issued 
CEXIT supervisor call in the current link 
level. Abnormal termination (cancel) 
conditions will not be intercepted at the 
current link level. 


To specify user-program abnormal condition 
handling for the current and any subsequent 
link levels. The options specified may be 
negated via the CANCEL option or reset via 
another SET option at the current link level, 
or may be temporarily overridden at subsequent 
link levels via the SET option issued therein. 


Operand Descriptions 


NODEBUG is 


DUMP = 


NOHELP = 


The Debug Processor is bypassed for abnormal 
termination conditions. Control is passed 
directly to the Cancel Command Processor 
without direct user notification. 


Similar to the NODEBUG option, this option also 
provides a full program dump prior to entry 
into the Cancel Command Processor. 


Causes HELP key to be disabled at current link 
level for the purposes of entry into the HELP 
Processor. If NOHELP is specified, pressing 
the HELP key in user mode has the _ following 
effects: 1) If the workstation does not have 
operator privileges, the alarm is sounded; 2) 
If the workstation is a dual mode operator 
console, operator mode is entered. This option 
remains in effect until a CEXIT without the 
NOHELP option is issued or until the program 
unlinks back to either the Command Processor's 
Initiator or a link level for which NOHELP was 
not specified. Unless specifically disabled 
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CEXIT 


therein, the NOHELP option is propagated to 
higher link levels. The NOHELP option should 
only be utilized in situations in which user 
access to CANCEL and other system functions 
must be limited, such as in the case of 
critical sections of application programs 
updating multiple file chains and pointers. 


Such programs should be highly debugged prior 
to use of this facility. 


ADDRESS= - Specifies the address of a user-program 
provided cancellation intercept routine. This 
routine gains control from the Cancel Command 
Processor in the following manner: 


If the abnormal termination condition occurred within the same 
link level, the Cancel Command Processor returns control to the 
program at the address of the cancellation intercept routine. 
(This routine may also gain control if the current or any 
subsequent link level issues a LOGOFF SVC and this CEXIT option 
is still active.) The registers are those at the time of either 
the program check or entrance to the supervisor call resulting in 
the abnormal termination condition. Thus, addressability should 
not be assumed. If the abnormal condition occurred while Data 
Management for either disk or tape was in control, an attempt is 
made to complete that operation. All non-I/O wait conditions are 
removed. The Cancel Command Processor does not, in this case, 
attempt to close any files. 


If the abnormal termination condition occurred within a 
subsequent link level, i.e., a "Linked-to" program, for which no 
cancellation interception routine was specified, the Cancel 
Command Processor successively attempts to complete I/O 
operations and close files and then UNLINK each link level until 
a link level with a cancellation interception routine (if any) is 
found, at which point control is passed to that routine. In this 
case, the registers are those at entry to the LINK supervisor 
call. As in previous cases, all non-I/O wait conditions are 
removed. 


In both cases, entry to the cancellation intercept routine 
cancels the CEXIT options for the link level. They may, if 
desired, be reset via a subsequent CEXIT supervisor call. On _ the 
stack, the cancellation intercept routine finds the following 
data (which may be accessed symbolically via the DSECT produced 
by the CXT macroinstruction): 


CANCELLATION PCW “ 8 Bytes 
PROGRAM NAME = 8 Bytes 
(Reserved) 7 48 Bytes 
GENERAL REGISTERS 0-15 = 64 Bytes 
CANCEL MSGLIST = Variable Length 
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MESSAGE = 


CEXIT 


Provides text to be used by both the Help Processor 
and the Debug Processor in place of the "CANCEL 
PROCESSING" menu descriptions. Specification is of 
a segment 2 location containing a one byte binary 
length field followed by up to 27 bytes of text. 
Specification of this option is independent of any 
user cancellation intercept routine specification. 


CEXIT SET,NODEBUG ,ADDRESS=FIXPROBS ,MESSAGE=CANCELME 
PUSHA 0,0 

MVI 0(15) ,B'00000000' 

MVI 1(15) ,B'00000000' 

PUSHA 0,CANCELME 

PUSHA 0,FIXPROBS 

MVI 0(15) ,B'10100000'OPTIONS BYTE 

SVC 39 (CEXIT) 
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Check For Event Occurrence 


syntax 
(1) [label] CHECK {OFB} = {address } [,ERREXIT= {address }] 
{VCB} { (register)} [ { (register) }] 
[ ,IOSWREG=RO] 
(2) [label] CHECK INTERVAL 
(3) [label] CHECK MESSAGE= {address } »PORT= {address } 
{ (register) } { (register) } 
{'string' } 
(4) [label] CHECK WSKEY = {address } 
{ (cegister) } 
(5) [label] CHECK INTERRUPT= {address } ,IOSWADDR= {address } 
{ (register) } { (register) } 
(6) [label] CHECK TCIO, OFB= {address } 


{ (register) } 


[,IOSWADDR= {address }] 
[ {register }] 


(7) [label] CHECK MULTIPLE,PLIST= {address  } 
{ (register) } 


,»COUNT= {self-defining term} 
{ (register) } 


Restrictions 


CHECK OFB or VCB should be issued only after issuing an XIO call. 


Function 


(1) CHECK OFB or VCB waits for completion of an I/O operation. 
If ‘intervention required’ is indicated on completion, CHECK 
issues an appropriate workstation message (if possible) to 
inform the user, and proceeds when’ the ‘intervention 
required' condition has been cleared. (CHECK may reissue 
the message if the condition has not actually been 
corrected.) CHECK waits for completion again after the 
condition has been cleared. If the operation has not 
completed, CHECK suspends processing of the issuing program 
until completion. If the ERREXIT operand is provided, CHECK 
returns to the specified address in the event of a permanent 
error completion (IOSW bit EC set, bits NC or IRQ not set). 
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CHECK 


Otherwise CHECK returns to the next sequential instruction 
address. CHECK logs I/O errors by means of a nonresident 
subroutine. 


(2) CHECK INTERVAL waits for expiration of a timing interval as 
set by the SETIME macroinstruction. 


(3) CHECK MESSAGE waits for a message to be sent to the issuing 
task. 


(4) CHECK WSKEY waits for a Program Function Key to be struck on 
the specified workstation, which must be reserved for use by 
the issuing task. An un-CHECKed xXIO request must not be 
outstanding to this workstation when this CHECK is issued. 


(5) CHECK INTERRUPT waits for an unsolicited interrupt from a 
workstation, a printer, or a telecommunications device. 


(6) CHECK TCIO waits for the occurrence of a TC I/O event. This 
event may be a completion of an I/O operation which was 
previously initiated by a call of the XIO SVC by the RECEIVE 
or TRANSMIT macro. This event may also be an_ unsolicited 
interrupt from a Data Link Processor (DLP) if no previous 
I/O command was issued. 


(7) CHECK MULTIPLE waits for any one of several specified events 
to occur. These can be any of (1) through (6) above. For 
details of parameter list construction, refer to the CHECK 
SVC description (SVC 17). 


NOTE: A FORM=LIST operand may be used with functions 1-6 above 
to build a multiple CHECK list on the stack. For example, 


CHECK INTERVAL, FORM=LIST 

CHECK WSKEY=(R1) , FORM=LIST 

LR R9,SP 

CHECK MULTIPLE, PLIST=(R9) ,COUNT=2 


will build a multiple CHECK list which waits on a PF key or a 
timer, in that order. After the call to CHECK MULTIPLE, the top 
stack word will contain the offset into the parameter list of the 
event that occurred. The parameter list remains on the stack. 


Operand Descriptions 


OFB= For the OFB option, the address of the Open File 
Block (OFB) for a file previously OPENed. Must be 
presented as an address expression, or as a 
register specification in parentheses where the 
register contains the address of the OFB. 
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VCB= 


ERREXIT= 


TOSWREG= 


MESSAGE= 


PORT= 


For the TCIO option, OFB= points to the address of 
the Open File Block (OFB) for the I/O channel 
device used in the I/O operation initiated by the 
corresponding RECEIVE or TRANSMIT call. The 
address supplied in the OFB= operand is an address 
pointing to a four-byte field containing the 
address of the OFB in the low-order three bytes. 


The address of a Volume Control Block (VCB). May 
be used only if the caller is in System Mutual 
Exclusion (SME) or the volume is mounted for 
initialization. Must be presented as an address 
expression, or as a register specification in 
parentheses where the register contains the 
address of the VCB. Note that the displacement 
constant of tl is added to the VCB address by the 
macroinstruction code in order to distinguish the 
CHECK VCB option from the CHECK OFB option. 


Optional address of an instruction to receive 
control in the event of an4I/O error. Must be 
presented as an address expression, or as a 
register specification in parentheses where the 
register contains the error exit address. 


If IOSWREG=RO is specified, the completion IOSW 
Will be returned in general registers 0 and 1. 


An address in segment 2, into which a received 
message will be placed. The receipt area in 
segment 2 must contain the total length of the 
area, in binary, in its first two bytes. The 
length must not be greater than 2016 bytes. The 
message is placed in the specified area. If the 
area length is less than the message length plus 
two, the message will be truncated on the right. 
The area length bytes are updated to reflect the 
length of the message, plus. two. (This is the 
full length of the message, even if the message 
was truncated.) 


The four-character name of one of this task's 
active message receipt ports, as established by 
CREATE. May be specified as an expression 
addressing a 4-byte field containing the port 
name, aS a register in parentheses pointing to the 
4-byte field containing the port name, or as a 
character string in single quotes which is. the 
port name. 
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WSKEY= A workstation device number. Specified in the 
low-order byte of the 4-byte field pointed to by 
an address expression, or in the low-order byte of 
a register in parentheses. 


INITERRUPT= The device number of a workstation, printer, or 
telecommunications device. May be specified in 
the low-order byte of the 4-byte field pointed to 
by an address expression, or in the low-order byte 
of a register in parentheses. 


IOSWADDR= An address in segment 2, into which the I0SW will 
be placed. May be specified as an address 
expression, or as a register in parentheses 
containing the address of the fOSW receipt area. 
This operand is required for the CHECK INTERRUPT 
option and for the CHECK TCIO option if the CHECK 
is for a TC unsolicited interrupt. 


The IOSWADDR operand is not required for the TCIO 
option if CHECKing for completion of an TC 1/0 
event. 


PLIST= Address of a parameter list for CHECK MULTIPLE. 
May be specified as an address expression, or as a 
register in parentheses containing the address of 
the parameter list. 


COUNT= Number of events (PLIST entries) for CHECK 
MULTIPLE. May be specified as a _ self-defining 
term which is the number of events, or asa 
register in parentheses containing the number of 
events (in binary) in the low-order byte. 


Example 
LAB1 CHECK OFB=(R2) ,ERREXIT=ERROR 
+LAB1 PUSHA 0,ERROR 
+ PUSH 0,R2 
+ SVC 17. = (CHECK) 
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Close File 


Syntax 
{iabel] CLOSE [REEL »] UFB={ (register) } 
[NOREWIND , ] {expression} 
[UNLOAD ,] 
Restrictions 
None. 
Function 


Closes a file (removes it from processable status) . Places 
the User File Block (UFB) in a state in which an OPEN can 
be addressed to it to return the file to  processable 
Status. This includes placing sufficient file location 
information in the UFB so that a succeeding OPEN will refer 
to the same file, volume, and device. If UFB bit UFBF1WORK 
is set and the file is in a library named #xxxWORK (where 
xxx is the USERID), the file will be SCRATCHed as well as 
CLOSEd. (See the SCRATCH supervisor call for function.) 


Operand Descriptions 


UFB= The address of a User File Block for an open 
file. It must be presented as a register 
specification in parentheses, where the 


register is assumed to contain the UFB address, 
or as a UFB address expression not in 
parentheses. If omitted, only the SVC 
instruction is generated. 


REEL If specified for a file on an _ appropriate 
device (e.g., magnetic tape), the file will not 
be closed, but rather will be positioned so 
that the first record on the next volume (if 
any) will be provided on the next READ, or 
written on the next WRITE. 


NOREWIND If specified for a magnetic tape file, 
rewinding is suppressed when the file is closed. 


UNLOAD If specified for a magnetic tape file, the tape 
will be rewound, set to "offline," and 
effectively DISMOUNTed when the file is closed. 


Example 
LAB1 CLOSE UFB=(R3) 
+ PUSH 0,R3 
+ Svc 1 (CLOSE) 
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Create Intertask Message Port 


Syntax 


[label] CREATE PORT= {(register)} ,BUFSIZE= { (register) } 


Function 


{expression} {expression} 
{'string' } 


{ ,PRIVILEGED] 


Activates an intertask message receipt port with the 
specified port name, and with the issuing task as the valid 


receiver. 


Optionally screens out messages not’ transmitted 


by code in privileged state or dedicated system tasks. 


Return codes are placed in the word on the stack top as 


follows: 
0 - Successful. 
4 ~ Another task has activated the specified port name. 
8 - Same task has already activated the specified port 


12 


name. 


GETMEM failure. 


Operand Descriptions 


PORT= 

BUFSIZE= 

PRIVILEGED 
Example 

LAB] CREATE 

+LAB1 PUSHC 

+ PUSH 

+ MVI 

+ SVC 


The four-character name of a message receipt 
port (chosen by the issuing program; any 
characters are allowed). May be specified as a 
register in parentheses pointing to the port 
name, as a literal in single quotes which is 
the port name, or as an expression addressing a 
4~-byte field containing the port name. 


The space in bytes to be allocated for 
buffering messages. May not be greater than 
2016. 


Causes only messages transmitted by tasks in 
privileged code or by dedicated system tasks to 
be received by the message receipt port being 
created. : 


PORT=PORTNAME , BUF SI ZE= (RO) 
0(4,0) ,PORTNAME 

0,R0 

0(15) ,x'00' 

37 (CREATE) 
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Return CEXIT ‘RETURN' Information 


Syntax 


Function 


The CXT macroinstruction allows the user to 


CxI {[NODSECT] [,REG=expression] [,SUFFIX=character] 


symbolically 


reference the information returned to a program's cancellation 
interception routine. 


Operand Descriptions 


NODSECT = Specification of NODSECT results in the CxXT 
fields to be assembled as part of the current 
CSECT, DSECT, or STATIC’ section. If not 
specified, a DSECT with the name CXT (+ SUFFIX) 
is generated. 

REG= = Provides for the optional specification of a 
register for which a USING statement for the 
CXT fields is generated. 

SUFFIX= = If provided, all labels are generated by the 
concatenation of 'CxT', the user-provided 
SUFFIX (one ASCII character in length), and the 
field name. 

Example 

CXT 

+CXT DSECT 

+% THE CEXIT RETURN INFORMATION BLOCK IS RETURNED TO 

+% A PROGRAM'S CEXIT ROUTINE FOR PROGRAMMED ANALYSIS 

+% OF AN ABNORMAL TERMINATION CONDITION. 

+CXTBEGIN DS OF (FULLWORD ALIGNMENT) 

+CXTPCW DS CL8& CANCELLED PROGRAM'S PCW 

+CXTPROGRAM DS CL8 NAME OF CANCELLED PROGRAM 

+e (x'00' IF UNABLE TO OBTAIN 

+% BUFFER DURING CANCEL 

+* PROCESSING!) 

+CXTFLAGS DS = XL1 VALUE IN PFBCXTOPTS AT TIME 

+7 OF PROGRAM CANCELLATION 

+CXTSPARE DS CL47 (RESERVED) 

+CXTREGS DS CL64 REGISTER'S OF PROGRAM 

+* AT TIME OF PROGRAM CANCEL 

+CXTMSGLIST DS OX CANCEL MSGLIST 

+CXTMSGID DS CL4& MESSAGE IDENTIFIER 

+CXTMSGISSUER DS CL6 MESSAGE ISSUER 

+CXTMSGLENGTH DS 4H MESSAGE LENGTH 

+CXTMSG EQU * MESSAGE BEGINS HERE 

+ CSECT 
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Delete Record from Indexed File 


Syntax 
[label] DELETE UFB={(register)} [,COND={integer }] 
{expression} [ {absolute expression}] 
Restrictions 


The file specified must be open for IO or SHARED mode 
processing. In I0 mode, the last function on this file 
must have been a successful READ with the HOLD option. In 
SHARED mode, the record to be rewritten must be held as a 
result of a READ with the HOLD option. 


Function 


To delete the last record read from an indexed file on 
disk. Normally, control is returned to the instruction 
location following the DELETE macroinstruction. If the 
record to be deleted is not held, if the file is not an 
indexed file, or if the DELETE function is not allowed for 
the current ‘open mode', control is returned to the I/0 
error return address as specified in the UFB, with the 
normal return address in register 0. If the I/O error 
return address in the UFB contains all binary zeroes when 
an error occurs, the program is abnormally terminated. 


File status bytes in the UFB are set as follows for DELETE: 


‘ Success UFBFS1=0, UFBFS2=0 
. I/O error UFBFS1=3, UFBFS2=0 
. Invalid function or UFBFS1=9, UFBFS2=5 


function sequence 


Operand Descriptions 


UFB= The address of a User File Block. It may be 
presented as a register specification, where the 
register is assumed to contain the UFB address, or 
as an expression not in parentheses, in which case 
the word addressed is assumed to begin the UFB. 


COND= If specified, the number or absolute expression 
becomes the first operand of the JSCI instruction 
by which the DELETE function is entered. Thus the 
DELETE is made conditional. COND=15 is the 
default. Register 1 is loaded with the UFB address 
in any case. 


+LAB2 


UFB= (R2) 
1,R2 
15,12(1) 


UFB=DSKUFB , COND=7 


1 ,DSKUFB 
7,12(1) 
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Destroy Intertask Message Port 
Syntax 


[label] DESTROY PORT= { (register) } 
{ expression} 
{ ‘literal' } 


Function 


Deactivates the intertask message receipt port with the 
specified port name, which must have been activated by the 
same task by means of the CREATE macroinstruction. 


Return codes are placed in the word on the stack top as 
follows: 


0 ~ Successful. 

4 - One or more messages were not received, and are 
lost; otherwise successful. 

8 - No such message buffer was allocated by this task. 


Operand Description 


PORT= The four-character name of a message receipt port. 
May be specified as a register in parentheses 
pointing to the port name, as a literal in single 
quotes which is the port name, or as an expression 
addressing a 4-byte field containing the port name. 


Example 
LAB1 DESTROY PORT=(R1) 


+LAB1 PUSHC 0(4,0) ,O(R1) 
+ SVC 38 (DESTROY) 
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Dismount Disk or Tape Volume 


Syntax 
[label] DISMOUNT VOLUME= {address  } » TYPE = {DISK} 
{ (register) } {TAPE} 
{'string' } 
,NODISPLAY= {YES} 
{NO } 
Restrictions 
None. 
Function 


To request the dismounting of a disk or tape volume. If the 
volume referenced is a tape volume, then it is also rewound and 
unloaded. 


DISMOUNT issues a return code to the user program in the stack 
top word which indicates the success/failure/status of the 
operation (see DISMOUNT SVC description for possible values). 


Operand Descriptions 


VOLUME= The name of the volume which is to be dismounted. 
It may be specified as as a register in parentheses 
pointing to the volume name, as a character string 
in single quotes which is the volume name, or as an 
expression addressing a 6-byte field containing the 
volume name. This operand is required. 


TYPE= Indicates whether the volume is a disk or a _ tape 
volume. Valid values are DISK and TAPE. This 
operand is optional and defaults to DISK. 


NODISPLAY= If YES is supplied, indicates that no messages 
are to be displayed on the user's workstation; the 
operator console messages must be used to coordinate 
physical dismounting. The default is NO. 
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Examples 


LAB DISMOUNT VOLUME='VOL444' ,TYPE = DISK 


+ LAB PUSHN 0,8 GET TWO WORDS ON THE STACK 

+ MVC 2(6,15) ,*+10 SET VOLUME NAME 

+ B *+10 BRANCH AROUND CONSTANT 

+ DC CL6'VOL444' VOLUME NAME 

+ MVI 0(15) ,x'00' SET FLAG FOR DISK VOLUME 

+ MVI 1(15) ,x'00! SET BYTE 1 to ZEROES (RESERVED) 
+ SVC 41 (DISMOUNT) ISSUE SVC 


LAB DISMOUNT VOLUME=(R4) 


+ LAB PUSHN 0,8 GET TWO WORDS ON THE STACK 

+ MVC 2(6,15) ,0(R4) SET VOLUME NAME 

+ MVI 0(15) ,x'00' SET FLAG FOR DISK VOLUME 

+ MVI 1(15) ,x'00' SET BYTE 1 TO ZEROES (RESERVED) 
SVC 41 (DISMOUNT) ISSUE SVC 

LAB DISMOUNT VOLUME=TAPEVOL , TYPE=TAPE 

+ LAB PUSHN 0,8 GET TWO WORD ON THE STACK 

+ MVC 2(6,15) ,TAPEVOL SET VOLUME NAME 

+ MVI 0(15) ,X'80' SET FLAG FOR TAPE VOLUME 

+ MVI 1(15) ,X'00' SET BYTE 1 TO ZEROES (RESERVED) 

+ SVC 41 (DISMOUNT) ISSUE SVC 
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Extract Data From System Control Blocks 


Syntax 

[label] EXTRACT FORM= {LIST } 

{BRIEF} 

{FULL } 

{PCPCW} 
AREA=al , NRES=a2, DYVAL=a3 , SYSVOL=a4, 
SYSLIB=a5, SYSWORK=a6, VERSION=a7 , OCNT=a8, 
WS=a9, STACK=al0, EXFLGS=all1, RDFLGS=al2, 
WIFLGS=al3, SEG2BUF=al4, USERID=al5, USERNAME=al6, 
EXTPRIOR=al7, PCPCW=al8, TASK#=al9, TASKTYPE=a20, 
CURVOL=a21, CURLIB=a22, WORKLIB=a23, SPOOLIB=a24, 
SEG2SIZE=a25, STATIC=a26, PRINTER=a27 , RUNVOL=a28, 

_ RUNLIB=a29, INVOL=a30, INLIB=a31, OUTVOL=a32, 
OUTLIB=a33, PRNTMODE=a34, FILECLAS=a35 , LINES=a36, 
PROGVOL=a37 , PROGLIB=a38, WORKVOL=a39 , SPOOLVOL=a40, 
PRTCLASS=a41, FORM#=a42 , WSI0=a43, TAPEIO=a44, 
DISKI0=a45, PRINTIO=a46, OTIO=a47 , PICOUNT=a48, 
POCOUNT=a49 , SICOUNT=a50, SOCOUNT=a51 , ETIME=a52, 
PTIME=a53, DEVICE=(a54,a55) , VOLUME=(a56,a57), 


OTASK=(a58,a59) , TAPEVOL=(a60,a61) , DEVCNT=a62, 


ATOETRT=a63, ETOATRT=a64, DEVLIST= (a65 ,a66,a67) , 
VERSION=a68, SYSPAGE=69, CPU=a69, HZ=a70, 
UEXFLGS=a71, URDFLGS=a72, UWIFLGS=a73, CLUSTER=a74, 
JOBQUEUE=a75, JOBCLASS=a76, JOBLIMIT=a77, JOBNAME=a78, 


DLPNAME=(a79 ,a80) , 
CDISKET=a83 , VOLVCB= (a84 ,a85) 


DLPDEV#= (a81 ,a82) , 


Restrictions 

None. 

Function 
Retrieves data from system control blocks that may be 
useful to user programs. 
The following outputs for FORM = BRIEF, FORM = FULL, or 


FORM = PCPCW are placed in the area addressed by the AREA= 
operand, by ascending addresses: 


FORM=BRIEF : 
(1) Total physical area in bytes not currently 
resident (4 bytes) 
(2) Number of files which a task may have open 


simultaneously (2 bytes) 
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FORM 


FORM 


(3) 


EXTRACT 


Workstation number associated with requesting 
task, or -1 if none (2 bytes) 

Remaining stack space in bytes after return from 
EXTRACT (4 bytes) 


Total physical area in bytes not currently 
resident (4 bytes) 

Number of files which a task may have open 
simultaneously (2 bytes) 

Workstation number associated with requesting 
task, or -1 if none (2 bytes) 

Remaining stack space in bytes after return from 
EXTRACT (4 bytes) 

One day in clock units (4 bytes) 

System default library's volume name (6 bytes) 
System default library name (8 bytes) 

Task's default printer number, or -1 if none (2 
bytes) 

User program library volume (6 bytes) 

User program library name (8 bytes) 

Current file-access bit map for ‘execute’ access 
(from Program File Block (PFB)) (4 bytes) 

Default non-output volume for ‘OPEN’ (6 bytes) 
Default non-output library name (8 bytes) 

Current file-access bit map for ‘read' access 
(from Program File Block (PFB)) (4 bytes) 

Default output volume for ‘OPEN’ (6 bytes) 

Default output library name (8 bytes) 

Current file-access bit map for ‘update’ access 
(from Program File Block (PFB)) (4 bytes) 

Number of segment 2 buffer pages currently 
available (2 bytes) 

Print output mode (Spooled (S), Keep (K), Hold 
(H) , or On-line (0)) (1 byte) | 

Default output file-protection class, or blank (1 
byte) 

User logon identification (3 bytes) 

Task current paging priority (from Task Control 
Block) (1 byte) 

Suggested lines-per-page for print files (1 byte) 
Operating System version number (Packed number 
‘VVRRPP' where VV is the version, RR is the 
revision, and PP is the patch level) (3 bytes) 


Program Control Word (PCW) at time of most recent 
program exception for which a user exit was 
specified (8 bytes) 
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EXTRACT 


Operand Descriptions 


FORM= 


AREA= 


BRIEF is used to request four items as described 
above. Thus the output area must be at least 12 bytes 
long. FULL is used to request all 20 items. listed 
above, and thus the output area must be at least 98 
bytes long. PCPCW is used to request the value of the 
Program Control Word (PCW) current when a program 
exception occurred for which an exit routine was 
provided, and is intended for use in such a routine. 
(Its use at other times results in undefined and 
irrelevant output.) The output area must be at least 
8 bytes long. LIST is used when a list of needed 
items is supplied. 


Specifies the address of the output area, either as an 
expression addressing that area, or as a register 
expression in parentheses, where the register contains 
the address of the area. Not valid with FORM=LIST. 


The following operands are used with FORM = LIST. only.. The 


operand  s 

correspondi 

SYSTEM-WIDE 
NRES= 
DYVAL= 
SYSVOL= 
SYSLIB= 
SYSWORK= 
VERSION= 
SYSPAGE= 
DEVCNT= 


ATOETRT= 


ETOATRT= 


CDISKET= 


CPU= 
HZ= 


pecifies the address of an area to receive the 
ng data item. 


INFORMATION: 


Total physical area in bytes not currently 
resident (4 bytes) 

One day in clock units (4 bytes) 

System default library's volume name (6 bytes) 
System default library name (8 bytes) 

System work library (paging files, system task 
queues, etc.) which BACKUP skips (8 bytes) 
Operating System version number (Packed VVRRPP, 
where VV is the version, RR is the revision, and 
PP is the patch level) (3 bytes) 

System paging library name (8 bytes) 

Device number (=255) of highest-numbered I/O 
device on the system (4 bytes) 

ASCII-to-EBCDIC translate table (256 bytes). 
See TR instruction in Principles of Operation 
Manual for use. 

EBCIDIC-to-ASCII translate table (256 bytes). 
See TR instruction in Principles of Operation 
Manual for use. 

Device number of system's central diskette (2 
bytes) 

Current CPU ID (2 bytes) 

A/C line frequency (2 bytes) 
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OCNT= 


WS= 
STACK= 
EXFLGS= 
RDFLGS= 
WIFLGS= 


UEXFLGS= 


URDFLGS= 


UWIFLGS= 


SEG2BUF= 
USERID= 
USERNAME= 
EXTPRIOR= 
PCPCW= 


TASK#= 


TASKTYPE= 


CURVOL= 
CURLIB= 


WORKLIB= 
SPOOLIB= 
JOBNAME= 


SEG2SIZE= 
STATIC= 


EXTRACT 


TASK-RELATED INFORMATION: 


Number of files which current task may have open 
simultaneously, excluding files already open (2 
bytes) 

Workstation number associated with requesting 
task, or -1 if none (2 bytes) 

Remaining stack space in bytes after return from 
EXTRACT (4 bytes) 


Current file-access bit map for ‘execute’ access 
(from Program File Block (PFB)) (4 bytes) 
Current file-access bit map for ‘read' access 
(from Program File Block (PFB)) (4 bytes) 
Current file-access bit map for ‘update’ access 
(from Program File Block (PFB)) (4 bytes) 
User's base file-access bit map for ‘execute’ 


access (from user's Extended Task Control Block 
(ETCB)) (4 bytes) 

User's base file-access bit map for ‘'read' 
access (from user's Extended Task Control Block 
(ETCB)) (4 bytes) 

User's base file-access bit map for 
‘update'access (from user's Extended Task 
Control Block (ETCB)) (4 bytes) 

Number of segment 2 buffer pages currently 
available (2 bytes) 

User logon identification (3 bytes) 

User name (from system user list) (24 bytes) 
Task's current paging priority (from Task 
Control Block) (1 byte) 

Program Check Old PCW for last program check (8 
bytes) 

Unique task identifier (4 bytes) 

Task type ('F' for foreground, 'FS' for 
dedicated foreground system task, ‘'B' for 
background task, and _ ‘'BS' for dedicated 
background system task) (2 bytes) 

Volume where current program resides (6 bytes) 
Library in which current program resides (8 
bytes) 

Work library name constructed from user ID or BG 
task number (8 bytes) 

Spool library name constructed from user ID or 
BG task number (8 bytes) 

Name of background job (8 bytes) 

Length of segment 2, in bytes (4 bytes) 

Pointer to beginning of static areas for current 
program (May be useful in re-establishing 
addressability in a CEXIT routine) (4 bytes) 
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USER DEFAULTS (May be set by using the SET SVC or the SET Command 
Processor function): 


PRINTER= Task's default printer number, or -1' if none (2 
bytes) 

RUNVOL= User program library volume (used by Command 
Processor RUN function) (6 bytes) 

RUNLIB= User program library name (used by Command 
Processor RUN function) (8 bytes) 

INVOL= Default non-output volume for OPEN (6 bytes) 

INLIB= Default non-output library (8 bytes) 

OUTVOL= Default output volume for OPEN (6 bytes) 

OUTLIB= Default output library (8 bytes) 

PRNIMODE= Default print output mode (1 byte) 

FILECLAS= Default output file-access protection class, or 
blank (1 byte) 

LINES= Suggested lines-per-page for print files (1 byte) 

PROGVOL= User program volume name used by LINK SVC (6 
bytes) 

PROGLIB= User program library used by LINK SVC (8 bytes) 

WORKVOL= Default work volume (6 bytes) 

SPOOLVOL= Default spool volume (6 bytes) 

PRTCLASS= Default print class for print files (A-Z) (1 
byte) 

FORM#= Default form number for print files (0-254) (1 
byte) 

JOBQUEUE= Default job status (Run (R) or Hold (H)) (1 byte) 

JOBCLASS= Default job class (A-Z) (1 byte) 

JOBLIMIT= Default job CPU time limit (4 bytes) 


RUN STATISTICS: 


WSIO= Count of workstation I/Os this run (4 bytes) 

DISKIO= Count of disk I/Os this run (4 bytes) 

TAPEIO= Count of tape I/Os this run (4 bytes) 

PRINTIO= Count of printer I/Os this run (4 bytes) 

OTIO= Count of I/Os for other devices not included 
under WSIO, DISKIO, PRINTIO, or TAPEIO (4 bytes) 

PICOUNT= Program pagein count (4 bytes) 

POCOUNT= Program pageout count (4 bytes) 

SICOUNT= System pagein count (4 bytes) 

SOCOUNT= System pageout count (4 bytes) 

ETIME= Elapsed time of run since command processor 
initiation, in hundredths of seconds (4 bytes) 

PTIME= Processor time of run since command processor 


initiation, in hundredths of seconds (4 bytes) 
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The following operands are used with FORM=LIST only. Two 
addresses are supplied. The first address specifies further 
input, and the second address specifies as area to receive the 


corresponding data. 


DEVICE= Input: 
Output: 


(1) 
(2) 
(3) 
(4) 


(5) 


(6) 

(7) 
VOLUME= Input: 

Output: 

(1) 

(2) 

(3) 


(4) 


(5) 


(6) 
7) 
(8) 
(9) 


(10) 
(11) 


(12) 
(13) 
OTASK= Input: 


Output: 
(1) 


Device address (1 byte) 


Device class (1 byte) 

Device type (1 byte) 

Usage - ‘EX’ (exclusive, ‘SH’ (shared)' or 
‘pDT' (detached) (2 bytes) 

Task identifier of device owner, or -l if 
none (4 bytes) 

Volume name number of removable volume (disk 
or tape only). Blank if nothing mounted. (6 
bytes) 

Volume name of fixed volume (disk only). 
Blank if nothing mounted. (6 bytes) 

4 bytes of binary zeroes (reserved) 


Volume Name (6 bytes) 


Device address, or -1 if volume not mounted 
(1 byte) 

Volume type: 'F' for fixed, '‘'R‘ for 
removable, or blank if not mounted (1 byte) 
Label type: 'SL' (standard label), 'NL' (no 
label), or blank if not mounted (2 bytes) 
Usage - '‘SH' (shared), 'RR' (restricted 
removal) , *PR' (protected) , "EX' 
(exclusive) , or blank 

Task identifier of volume mounter, or -1 if 
none (4 bytes) 

Blocks per cylinder (2 bytes) 

Maximum transfer in bytes (2 bytes) 

Cylinders per volume (2 bytes) 

Cylinders per physical volume, including bad 
or unused blocks (2 bytes) 

Number of files open on this volume (2 bytes) 
Sector type (diskette only): soft sector 
(S), hard sector (H) 

Addressing in effect (diskette only): 
Non-standard (N), Standard (S) 

Unused (2 bytes) 


Task identifier (4 bytes) 


Workstation device number of task specified, 
or -1 if none (1 byte) 
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TAPEVOL= 


DLPNAME= 


(2) Current user ID for task specified, or blank if 
none (3 bytes) 
(3) Current user name for task specified, or blank 
- if none (24 bytes) 
(4) Type ('F', 'FS', ‘B', ‘BS') of task specifed 
(see TASKTYPE) (2 bytes) 
(5) 18 bytes of binary zeroes (reserved) 


Input: Volume name (6 bytes) 

Output: 

(1) Device address, or -1 if volume not mounted (1 
byte) 

(2) 1 byte of binary zeroes (reserved) 

(3) Density, BPI in binary: 556, 800, or 1600 (2 
bytes) 

(4) Label type: ‘AL’ (ANSI), 'NL' (no label), ‘IL' 
(IBM label) , or blank if volume not mounted (2 
bytes) 

(5) Usage: 'SH' (shared), '‘EX' (exclusive), or 
blank if not mounted (2 bytes) 

(6) Task identifier of tape mounter, or -1 if none 
(4 byts) 

(7) Current file sequence number (2 bytes) 

(8) 6 bytes of binary zeroes (reserved) 


Input: Name of Data Link Processor (as specified in 
the SYSGEN procedure) 


NOTE: 
The output area will be all zeroes if the specified 
DLP name is invalid. 


Output: 
(1) Bit map of devices on DLP (4 bytes) 
(2) First device on DLP (2 bytes) 
(3) Type of DLP (1 = 22V06-1, 2 = 22V06-2, 3 = 
22V06-3) (1 byte) 
(4) Number of lines (RS-232) controllable by the DLP 
(1 byte) 
(5) Microcode file status (X'00' if stopped, x'80' 
if loaded) (1 byte) 
(6) Reserved for future use (3 bytes) 
(7) Microcode file name (8 bytes, zero if not loaded) 
(8) Microcode library name (8 bytes, zero if not 
laoded) 
(9) Microcode volume name (6 bytes, zero if not 
loaded) 
(10) Reservation status of DLP (X'80' if 
reserved, X'00' if not reserved) 
(11) Task number of the task which reserved the 
DLP (3 bytes) 
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DLPDEV# Input: Device address (2 bytes) 


NOTE: 
For the DLPDEV# operand, the output area will contain 
zeroes if the specified device address is invalid. 


Output: 

(1) Device status flag (X'80' if open, X‘'40' if 
reserved, zero otherwise) 

(2) Task number of the task which reserved the DLP, or 
zero if device is unreserved (3 bytes) 

(3) Name of the DLP on which the device is SYSGENed (4 
bytes) 


CLUSTER= Input: Device number (2 bytes) 


NOTE: 
This operand is used for obtaining the device number of 
the archiver diskette on the same cluster as the device 
number which is specified as input. (If more than one 
archiver diskette is on the cluster, then the device 
number that is returned belongs to the archiver whose 
device number is next in sequence.) 


Output: 

(1) Device number of the archiver diskette, or zero if 
none (2 bytes) 

(2) Unused (14 bytes) 


VOLVCB= Input: Volume name (6 bytes) 


Output: Volume Control Block (VCB) address (4 bytes) 


The DEVLIST operand has three suboperands. The first address 
specifies further input, the second address specifies an area to 
receive the corresponding data, and the third suboperand is the 
length of the output area (specified as an expresssion or 
register in parentheses). Note that the maximum number of device 
addresses in the device list will be two less than the output 
length specified. 


DEVLIST= Input: Device class, as in EXTRDDEVCLASS (1 byte) 
Output: 
(1) Total number of devices for specified device class 
(1 byte) 
(2) Number of device addresses supplied (1 byte) 
(3) Device address list (1 byte for each device address) 
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++ eee eereree te t+ +eetetereet 


++ +++ 4+ + 


LAB1 
LAB1 


LAB2 


LAB2 


LAB3 
LAB3 


LAB4 
LAB4 


FORM=BRIEF , AREA= (R3) 


0,R3 
O(SP) ,0 
28 (EXTRACT) 


AREA 
FORM=BRIEF 


INLIB=A1 , INVOL=(R1) 


0,R1 

0,11 

0,Al 

0,12 

0,2 

0(15) ,3 

28 (EXTRACT) 


AREA FOR INVOL 
IDENTIFIER 
AREA FOR INLIB 
IDENTIFIER 
COUNT OF ITEMS 
FORM=LIST 


OUTLIB=Al , VOLUME=(A2, (R1)) 


0,Al AREA FOR OUTLIB 

0,15 IDENTIFIER 

0,1 COUNT OF ITEMS 

0(15) ,3 FORM=LIST 

28 (EXTRACT) 

0,A2 VOLSER ADDRESS 

0,R1 AREA FOR OUTPUT 

0(15) ,24 CURRENT OUTPUT LENGTH 
0,51 IDENTIFIER 

0,1 COUNT OF ITEMS 

0(15) ,4 FORM=LIST WITH ADDITIONAL INPUT 
28 (EXTRACT) 


DEVLIST=(A2, (R1) ,12) 


28 (EXTRACT) 
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DEVICE CLASS ADDRESS 

AREA FOR OUTPUT 

SPECIFIED OUTPUT LENGTRH 
IDENTIFIER 

COUNT OF ITEMS 

FORM=LIST WITH ADDITIONAL INPUT 


Generate Selected Parameter Group Control List Fields 


Syntax 


[label] FMTLIST [LABELPFX=' prefix’ ,] 
‘Keyword’, ({'displayed-value'} 
{ absolute-length } 


{,line-advance] [,space-advance]) , 


{TEXT, } 
{textname,} ('displayed-text' 
[,line-advance] [,space-advance] 


{ 
{ 
{ 
{ 
{ 
{ 
{ 
{ 
{ 
{ 
{ 
{ 
{ 
{ 
{ 
{ 
{ [,'CENTER'][,*RIGHT']) 


geet eyed aged Sayed Cages Cage Rage eget Cage Ceyet eget yet eye et p ege 


['Keyword2',(...),...] 


[PREVIEW = {YES}] 
{NO} 


Function 


Generates Field Format Control Blocks for use in a 
Parameter Group Control List as addressed by SVC GETPARM 
and SVC PUTPARM. The function is identical to that of the 
KEYLIST macroinstruction, except that the first eight bytes 
of the Parameter Group Control List are not generated. 
Thus, a PRNAME may not be specified. 


Operand Descriptions 


As for the KEYLIST macroinstruction, except that PRNAME may 
not be specified. 
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+XXXLIST 
+ 
+ 


FMTLIST 
TEXT1, (*HEADING' 


LABELPFX='XXX' , 
); 


TEXT , ('SUBHEADING') , 


'LIST' , ('NO* ,AN) 
EQU 


SaSS8SS8 S888 


% 


HL1'0' PF KEY 
HL1'3' FIELD COUNT 
HL1'1,0,-1.6' 
C'HEADING' 
HL1'1,0,-1,9' 
C'SUBHEADING' 
HL1'1,0,0,1' 
CL8'LIST' 

C'NO' 
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mms 


Free Buffer Space 


Syntax 


[label] FREEBUF BUFLOC={ (register) }[,LENCTH=(register) ] 
{ expression} 


Restrictions 


For use by certain supervisor call routines and Data 
Management System routines only. 


Function 


To deallocate a buffer area allocated by GETBUF. The 
buffer area at the address (in segment 2, as provided by a 
preceding GETBUF) specified by the BUFLOC operand and for 
the length specified by the LENGTH operand is made 
available for reallocation by GETBUF. The contents of this 
area should be considered unreliable after the FREEBUF has 
been issued. 


A return code is left on the stack: 
0 - Buffer deallocated 


4 ~ Invalid buffer address 
8 ~ Invalid buffer length 


Operand Descriptions 


BUFLOC= The address of a buffer allocated by GETBUF. 
This must be presented as a register 
specification in parentheses, where the 


register is assumed to contain the buffer 
address, or as a buffer address expression not 
in parentheses. 


LENGTH= A register specification in parentheses where 
the register contains the buffer length. The 
length must be a multiple of 2048, and must be 
the same as that requested by GETBUF. LENGTH 
of 2048 is assumed if no LENGTH= operand is 


supplied. 
Example 
LAB1 FREEBUF BUFLOC= (R1) 
+LAB1 PUSHA 0 ,2048 
+ PUSH 0,R1 
+ svc 6 (FREEBUF) 
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Deallocate Heap Storage 


Syntax 
[label] FREEHEAP SIZE= (register) 
»LINKLEV= address 
»BUFLOC= { (register) } 
{address } 
»POOLNAME= {address } 
{'string' } 
[,ROOTLEV] [,SEARCH] [ ,DELETE] 
Restrictions 


A stack with the stack top addressed by the general 
register 15 must be available. 


Function 


Deallocates heap storage previously allocated by the 
GETHEAP SVC. 


Operand Descriptions 


SIZE= 


BUFLOC= 


The size of the block to be allocated. Specified 
as a register in parentheses where the register 
contains the size of the block in the low-order 
three bytes. When the deletion of an _ entire 
subpool is specified (i.e., the DELETE parameter 
is specified) , the SIZE parameter is ignored. 


Start address of the buffer/block to be deleted. 
Specified as a register in parentheses containing 
the start address of the buffer/block in the 
low-order three bytes, or as an address expression 
pointing to a 4-byte field which contains’ the 
Start address of the buffer/block in the low-order 
three bytes. When the deletion of an entire 
subpool is specified (i.e., the DELETE parameter 
is specified), the BUFLOC parameter is ignored. 
BUFLOC must be specified if DELETE is not 
specified. 
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LINKLEV= 


POOLNAME= 


ROOTLEV 


SEARCH 


DELETE 


Example 


LAB1 


+LAB1  PUSHN 


++ ete + + 


FREEHEAP 


Link level at which to start searching for the 
specified subpool. A value of '0' indicates the 
current link level, a value of '1' is the parent, 
and so on. Specified as an address expression 
pointing to a one-byte field containing the link 
level in binary. Default is 0 (i.e., current link 
level). 


Name of the subpool to be  searched/deleted. 
Specified as a 1- to 8&byte character string in 
quotes which is the name of the subpool, or as an 
address expression pointing to an 8-byte character 
string not in quotes. Blank names are _. not 
permitted. Trailing blanks are insignificant. 
There is a system-defined default poolname for 
each link level. 


If specified, sets the LINKLEV parameter to 255 
(X'FF'), which indicates the lowermost link 
level. Any other value specified with LINKLEV= is 
ignored if ROOTLEV is specified. 


If specified, a backward search for the subpool is 
to be initiated starting from the LINKLEV 
specified. Default is no backward search. 


If specified, asks for the deletion of an entire 
subpool. The SEARCH parameter is ignored if 
DELETE is specified. The BUFLOC parameter and 
SIZE parameter are ignored if DELETE is specified. 


FREEHEAP SIZE=(3) ,POOLNAME=NAMELOC ,BUFLOC=START ,ROOTLEV 


0,16 RESERVE STACK SPACE FOR PARAMETERS 
(16,15) ,0(15) INITIALIZE PARAMETER SPACE 
8(8,15) ,NAMELOC MOVE POOLNAME TO STACK 
2,B'0111',1(15) MOVE SIZE PARAMETER TO STACK 
5 (3,15) ,START MOVE START ADDRESS TO STACK 
4(15) ,X'FF' SET LOWERMOST LINK LEVEL 

57 (FREEHEAP) 
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Get Buffer Space 


Syntax 


[label] GETBUF [LENGTH=(register) ] 


Restrictions 


For use 
Management 


Function 
To allocat 


(page) b 
low-addres 


by certain supervisor call routines and Data 
System routines only. 


e a data management buffer area on a 2048-byte 
oundary. Buffer space is allocated from the 
s end of segment 2. Control register 2 (the 


stack limit word) may be modified by this function and by 


FREEBUF. 


Two words are stacked as output of this function: 


If a buffer is allocated, the top word of the 


stack contains binary zero, and the next word 
contains the buffer address. 


If a buffer cannot be allocated, the top word of 
the stack contains four in binary, and the next 
word's contents are undefined. 


Tf the requested length is not a multiple of 2K, 
the top word of the stack contains eight in 
binary, and the next word's contents are 
undefined. 


Operand Description 


LENGTH= 


A register specification in parentheses where the 
register contains the buffer length. Only 
lengths which are multiples of 2048 are valid. 
If the operand is omitted, LENGTH of 2048 is 
assumed. 


GETBUF 

PUSHN 0,4 

PUSHA 0 ,2048 
svc 5 (GETBUF) 
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Allocate Heap Storage 


Syntax 
[label] GETHEAP SIZE= (register) 
»LINKLEV= address 
»POOLNAME= {address } 
{'string'} 
{,ROOTLEV] [,ALIGN] [,SEARCH] [,CREATE] 
Restrictions 


A stack with the stack top addressed by general register 15 
must be available. 


Function 


This macro provides a user-level memory management feature 
known as heap storage allocation. Heap storage is storage 
independent of the system stack that can be allocated 
dynamically. The GETHEAP facility is a generalization of 
the GETBUF macro and SVC (for allocating page-aligned 
buffers) with the following additional features: 


1. Any size block can be allocated. It is not necessary 
for the size to be a multiple of 2K. Any size is 
automatically rounded up to the nearest 8—-byte multiple. 


2. Blocks may be put into different ‘subpools’. 
Advantages of subpooling are that clustering of areas 
allocated from the same subpool will tend to occur, and 
that blocks in a given subpool may be allocated in 
separate calls of the §GETHEAP macro and then 
deallocated together by one FREEHEAP call. 


3. All subpools associated with a specified link level are 
released automatically on UNLINK for that level. 


Because blocks are automatically released at program 
termination, present GETBUF users are encouraged to convert 
to GETHEAP. 
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GETHEAP 


Operand Descriptions 


SIZE= 


LINKLEV= 


POOLNAME= 


ROOTLEV 


ALIGN 


SEARCH 


CREATE 


The size of the block to be allocated. Specified 
as a register in parentheses where the register 
contains the size of the block in the low-order 
three bytes. 


Link level at which to start searching for the 
specified subpool. A value of '0' indicates the 
current link level, a value of '1' is the parent, 
and so on. Specified as an address expression 
pointing to a one-byte field containing the link 
level in binary. Default is 0 (i.e., current link 
level). 


Name of the subpool to be searched/created. 
Specified as a one- to eight-byte character string 
in quotes, or as an address of an eight-byte field 
containing an eight-byte character string not in 
quotes. Blank names are not permitted. Trailing 
blanks are insignificant. There is a 
system-defined default poolname for each link 
level. 


If specified, sets the LINKLEV parameter to 255 
(X'FF'), which indicates the “lowermost link 
level. Any other value specified with LINKLEV= is 
ignored if ROOTLEV is specified. 


When specified, requests 2K-alignment for all 
blocks which are a multiple of 2K in size. This 
parameter is ignored for blocks which are not a 
multiple of 2K. The default is no alignment. 


If specified, a backward search for the subpool is 
initiated starting from the LINKLEV specified. 
The default is to no backward search. 


If specified, asks for the creation of a new 
subpool with the name given by the POOLNAME= 
parameter and at the link level given by LINKLEV. 
The SEARCH parameter is ignored if CREATE is 
specified. 
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GETHEAP 


GETHEAP 


SIZE= (2) ,POOLNAME=' POOL’ , LINKLEV=LEVL , CREATE 
0,16 RESERVE STACK SPACE FOR PARAMETERS 
0(16,15) ,0(15) INITIALIZE PARAMETER SPACE 


8(8,15) ,*+10 MOVE POOLNAME TO STACK 

*+12 

CL8'POOL' 

2,B'0111',1(15) | MOVE SIZE PARAMETER TO STACK 

4(1,15) , LEVL MOVE LINK LEVEL PARAMETER TO 
STACK 

0(15) ,x'40' SET THE CREATE FLAG 

56 (GETHEAP) 
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Get Parameters 


Syntax 


{label 


] GETPARM [I ,]FORM={REQUEST} 
[1D,] {SELECT } 
[R ,] {ACK } 
[RD ,] {SYSHDR } 
{OPR } 
»KEYLIST={ (register1) } »MSG={ (register2) } 
{expression1} {expression?2} 
»DEVICE={ (register3) } [ PFKEYS={ (register4) } J 
{expression3} [ {expression4} J 
[ { (ENTER, expression4) }] 
on 


Functi 


To solicit formatted information from a procedure body or 
from the user's workstation. Fields for which values are 
requested are identified by a two-level name (PRNAME and 
Keyword) specified in the Parameter Group Control List 
addressed by the KEYLIST operand. The procedure body in 
effect, if any, is the preferred source of values for a 
type ‘I' (initial) request. In the absence of a matching 
name in a procedure, the user is solicited at the 
workstation. A type ‘ID' (initial defaulted) request 
solicits from the procedure body only. A type 'R' 
(respecification) request solicits from the workstation 
only. A type 'RD' request normally solicits no information 
from the workstation or from a procedure body, but updates 
the procedure's temporarily stored information for use by 
reference from a later procedure step. 


The MSGLIST macroinstruction may be used to generate a 
message for display. The KEYLIST macroinstruction may be 
used to generate the Parameter Group Control List addressed 
by the 'KEYLIST=' operand of GETPARM. 


The total number of lines utilized by KEYLIST and MSGLIST 
displays may not exceed 18. None of these lines may be 
longer than 79 characters, excluding end-of-line characters. 


The user should consult the GETPARM Supervisor Call 
description and the KEYLIST macroinstruction description in 
this document for details concerning the function of this 
macroinstruction. 
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GETPARM 


Operand Descriptions 


ID 


FORM= 


MSG= 


KEYLIST= 


DEVICE= 


Indicates the type of request. If not 
specified, 'I' is the default value. 


Valid options are shown in the syntax 
specification; these are: 


REQUEST - Request for information (default 


option) ; 
SELECT - Request for selection; 
ACK ~ Request for acknowledgment}; 


SYSHDR - Request for information with no 
PRNAME displayed; 
OPR - Request for operator action. 


For details, consult the GETPARM SVC 
description. 


The address of a message in the format 
specified in the GETPARM Supervisor Call 
description. This is the form of message 
generated by the MSGLIST macroinstruction. It 
may be presented as a register specification in 
parentheses, where the register contains the 
message address, or aS an expression not in 
parentheses, where the expression addresses the 
message. A message is always required, but the 
message text may be of length zero. 


The address of a keyword specification and 
display formatting list (format control list), 
in the format specified in the GETPARM 
Supervisor Call description. This is the 
format produced by the KEYLIST 
macroinstruction. This operand may be 
presented in the same ways as the ‘'MSG=' 
operand. A format control list is always 
required, but may if desired have no Field 
Format Control Blocks (Keyword or text 
specifications) . 


Device number in binary in the low byte of the 
specified register or at the byte in memory 
specified by the expression. Required if 
FORM=OPR is specified; displayed when FORM=OPR 
only. 
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GETPARM 


PFKEYS= 


LAB2 


LAB3 


If supplied as a single suboperand not in 
parentheses or if supplied in parentheses with 
the word ENTER (as shown in the syntax above), 
the designated expression is to be used in a 
4-byte A-type address constant indicating which 
program function keys are to be accepted. The 
high-order bit corresponds to program function 
key 1, the low-order bit to program function 
key 32. Bits on indicate keys to be accepted. 
This expression may be preceded by ‘ENTER,’ in 
which case the ENTER key is also accepted. 
Otherwise, if the 'PFKEYS=" operand is 
supplied, the ENTER key is not accepted. 


May also be specified by designating a register 
in parentheses where the register contains the 


program function key map. 


If the ‘PFKEYS=" operand is not supplied, the 
following keys are accepted: 

FORM=REQUEST ENTER only 

FORM=SELECT All PF keys and ENTER 
FORM=ACK ENTER only 

FORM=SYSHDR ENTER only 

FORM=OPR ENTER and PF key 16 only 


GETPARM KEYLIST=(R2) ,MSG=LAB2 

PUSH 0 ,R2 

LA 0, LAB2 

PUSH 0,0 

SVC 20 (GETPARM) 

MSGLIST °1234','TXTEDT','OPTIONS AS FOLLOWS:' 
KEYLIST PRNAME='OPT' , 


"LIST' , ('NO' ,AN,1,0) , 
"DISPLAY', ('YES' ,AN,1,0) , 
"LINECNT', ("50° , INT ,1,0) 
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X 
xX 
x 


Halt I/O Operation 


Syntax 


Restri 


1. [Label] HALTIO PRINTER { (register) } 
integer } 


{ expression} 


| 
am 


2. [Label] HALTIO OFB { (register) } 


expression} 


1 
paren 


ctions 


Intended for use by system routines and those user programs which 
must control I/0 operations thru "XIO" (Execute Physical I/0). NOT 
to be used by programs using normal DMS for I/O. 


HALTIO must not be issued unless an unCHECKed XIO is currently 
outstanding. The user program must always wait for the HALTIO to 
complete by issuing a subsequent CHECK I/O macroinstruction. 


Functi 


ons 


1. To terminate multi-line (especially block-oriented) print 1/0 
requests to a printer. 

2. To terminate an outstanding I/O request to/from a file which is 
not necessarily a printer output § file (especially 
telecommunications files). 

3. To terminate an outstanding volume-oriented I/O request to/from 
a disk. 


HALTIO issues a Return Code in the stack top word for the "PRINTER" 
form of the macroinstruction. This Return Code corresponds to the 
condition code set by the HIO machine instruction (see "VS 
Principles of Operation"). 


- HALTIO does not issue a Return Code for the "“OFB" or "'VCB" forms of 


the macroinstruction. The stack is cleared by the SVC. 


Operand Descriptions 


PRINTER - The device number of the printer whose current I/O is 
to be terminated. This number must be in the range 0 - 
255 and may be specified as a register in parentheses 
containing the device number in binary in its low-order 
position as an integer which is the device number in 
decimal, or as an expression addressing a one-byte 
field containing the device number in binary. 
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HALTIO 


OFB 


- The address of the Open File Block for the outstanding 
1/0. This form is used for file-oriented (regular) I/0 
and may reference any file/device pairing. This 
operand may be specified as a register in parentheses 
or as a four~byte data item defined in the user program. 


The two operands are, of course, mutually exclusive. 


HALTIO PRINTER=(R3) 


PUSHA 0,0 GET ONE WORD OF ZEROS ON THE 
STACK 

STC R3,3(,15) PUT PRINTER NUMBER IN LOW- 

ORDER BYTE 

Svc 12 (HALTIO) ISSUE SVC 

HALTIO PRINTER=3 

PUSHA 0,3 PUSH PRINTER NUMBER ONTO STACK 

SVC 12 (HALTIO) ISSUE SVC 

HALTIO PRINTER=PBLKID 

PUSHA 0,0 GET ONE WORD OF ZEROS FROM THE 
STACK 

MVC 3(1,15) ,PBLKID PUT PRINTER NUMBER IN 

LOW-ORDER BYTE 

SVC 12 (HALTIO) ISSUE SVC 

HALTIO OFB=(R4) 

PUSH 0,R4 PUSH OFB ADDRESS ONTO STACK 

MVI 0(15) ,x'80' FLAG AS OFB/VCB TYPE PARMLIST 

SVC 12 (HALTIO) ISSUE SVC 
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Generate Parameter Group Control List 


Syntax 


[label] KEYLIST PRNAME='name' , [LABELPFX='prefix' ,] 


{ 'Keyword1', ({'displayed-value'}, } 
{ { absolute-length } } 
{ } 
{ (,CHAR ] } 
{ {,1InNr ] } 
{ [,NUM ] } 
{ [,AN ] } 
{ [,HEX ] } 
{ [ ,UCHAR] } 
{ {[,ANL ] } 
{ } 
{ {,line-advance] [ ,space-advance]) , } 
{ } 
{ } 
{ } 
{ {TEXT, } } 
{ {textname} (‘displayed-text' } 
{ [,line-advance] [,space-advance]  } 
{ [,'CENTER'][,'RIGHT']) } 


('Keyword2',(...),...] 


[,PREVIEW = {YES}] 
{NO} 


Restrictions 


Intended for use in conjunction with the GETPARM macroinstruction. 
See that macroinstruction and the GETPARM Supervisor Call 


description. 
Function 
Generates a data structure suitable for use as a parameter group 


control list with SVC GETPARM (object of ‘KEYLIST=' operand of the 
GETPARM macroinstruction) . 
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KEYLIST 


Operand Descriptions 


PRNAME= 


LABELPFX= 


'Keyword' 


'displayed-value' 


absolute-length 


CHAR 


INT 


A name identifying the parameter 
group. May be up to eight characters 
in length; characters may be 
alphabetic and/or numeric (first 
character must be alphabetic). 


A character string in quotes which 
will be prefixed to each ‘'Keyword' 
name and the resulting string used to 
label each corresponding keyword 
block. The label is placed on the 
line-advance byte. Thus the flag byte 
is at the location specified by this 
label +2, and the receiving field 
('displayed-value') is at this 
location +12. This operand is 
optional. 


A name of up to eight alphabetic 
and/or numeric characters enclosed in 
single quotes, identifying a specific 
parameter within the group. 
Specification of 'Keyword' is mutually 
exclusive with specification of TEXT 
or text name. 


A character string in single quotes 
containing the default value for this 
specific parameter. Single quotes to 
appear in the string must be 
represented by two consecutive single 
quotes. The receiving field length is 
then the length oof this. string. 
Specification of ‘displayed-value’ is 
mutually exclusive with specification 
of absolute-length. 


An absolute expression must be 
provided defining the length of the 
receiving field for this parameter. 
Specification of absolute-length is 
mutually exclusive with specification 
of ‘displayed-value.' ; 


Any character accepted in receiving 
field. 


Only unsigned integers accepted. 


Numbers (with optional decimal point 
and/or leading sign) accepted. 
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HEX 


UCHAR 


ANL 


line-advance 


TEXT 
Textname 


KEYLIST 


Letters (including national characters 
#, @, and $) and numerals accepted. 
GETPARM will convert letters to upper 
case. 


Only numerals = and letters A-F 
accepted. Letters A-F converted to 
upper case. 


(Leading and trailing blanks’ are 
accepted in any format except 
alphanumeric [AN], wherein only 
trailing blanks are accepted.) 


Any characters accepted. Lowercase 
letters converted to uppercase. 


Letters (including national characters 
#, @, and &) and numerals accepted. 
GETPARM will convert letters to 
uppercase. The first character must 
not be a number. 


A positive number, zero, or omitted 
(in which case 1 is assumed). If 
nonzero, the keyword oor text is 
displayed starting in column 2 (plus 
the value in the space~advance 
suboperand) of the line which is the 
specified number of lines in advance 
of the current line. If zero, line 
advancing does not occur, and one 
space (plus the number of spaces 
specified by the Space~advance 
suboperand) appears on the workstation 
screen between the previous displayed 
values and this keyword or text. 


Indicates that embedded text, rather 
than a keyword and receiving field, is 
supplied in the next operand. Ifa 
nonquoted textname is provided, it may 
be used to symbolically address the 
beginning of the actual text field in 
the Parameter Group Control List, 
i.e., the label "textname"™ is 
generated for the specified text field. 
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KEYLIST 


space-advance 


‘displayed-text' 


If specified as either an expression 
with a value no less than zero or 
greater than 78, or omitted (in which 
case, zero is assumed), the value of 
space-advance plus 1 is the number of 
spaces that will appear on the 
workstation screen between either the 
previous field (if zero line~advance) 
or the left side (if nonzero 
line-advance) and the keyword or text 
of the current field. 


The space~advance may also. be 
specified in three alternative formats: 


*Ann' 


“nn" represents one or two digits with 
a value no less than "2" and no 
greater than "80" that indicate the 
"absolute" column in which the field 
is- to begin. The appropriate 
field-advance value is calculated and 
placed in the control block. 


"CENTER ' 


The appropriate field-advance value is 
calculated (and placed in the control 
block) such that the field is centered 
within the 80 column workstation 
screen line. 


"RIGHT' 


The appropriate field-advance value is 
calculated (and placed in the control 
block) such that the field is 
right-justified on the 80 column 
workstation screen line. 


Regardless of how the space-advance is 
specified, a MNOTE is generated if an 
attempt is made to generate a 
workstation line over 80 characters in 
length or if an absolute, centering, 
or right~-adjust request cannot be 
honored. 


A character string in quotes to be 
displayed as embedded text. 
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‘Keyword2 


PREVIEW 


Example 


+ALIST 

+ 

+ 
+ADISPLAY 
+ 

t 

> 

+ 
+ALINECNT 
+ 

+ 


i] 
geooe 


KEYLIST 


"LIST', (‘'NOb',AN) , 
‘DISPLAY' , ('YES' ,AN,0,5), 
TEXT, (‘NUMBER OF LINES'), 


SSSSSSSSESSSSESES 


KEYLIST 


Any number of keyword or embedded text 
operands may be supplied. 


If YES is specified, the screen 
display specified by the 
macroinstruction operands will be 
printed in the source listing. NO is 
the default. 


PRNAME='OPT' ,LABELPFX='A', X 
Xx 
Xx 
x 

'LINECNT' , ('50', INT,O,5) 

CL8'OPT' PRNAME 

HL1'0' PF KEY 

HL1'4' FIELD COUNT 

HL1'1,0,0,2° LA ,SA,FLAGS , LGTH-1 

CL8'LIST' KEYWORD 

C'NOb' FIELD 

HL1'0,5,0,2' LA ,SA,FLAGS , LGTH-1 

CL8'"DISPLAY' KEYWORD 

C'YES' FIELD 

HL1'1,0,-1,14' LA ,SA,FLAGS , LGTH-1 

C'NUMBER OF LINES' 

HL1'0,5,1,1° LA,SA,FLAGS , LGTH-1 

CL8'LINECNT' 

c'50' 
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Link to Another Program or Subprogram 


Syntax 
[label] LINK [EP='literal' ] 
[EPLOC=Address of name] 
[ ,SYSTEM] [ ,NOFAIL] [ ,LOADONLY] 
[,LIBRARY={Address }] 
{*literal'} 
[, VOLUME ={Address }] 
{*literal'} 
Restrictions 


A stack, with stack top addressed by general register 15, 
must be available to the issuer. 


Function 


Pushes the name parameter and flag byte onto the top of the 
stack and invokes the specified program by SVC LINK. If 
the LIBRARY and VOLUME operands are specified, they 
override the user program library and volume specified on 
the SET or RUN command. The invoked program may return to 
the invoker by means of the RETURN’ amacroinstruction. 
Execution of the LINK macroinstruction pushes. status 
information onto the stack, as well as the 'static’ areas 
of the LINKed-to program as described in section 2.2.1.1.3 
of this document. Addresses on the stack to be passed to 
an invoked program should be placed in a parameter list 
addressed by register Rl. This parameter list may not be 
in the reentrant program segment (segment 1). On entry to 
a LINKed-to program, register R14 addresses the (new) 
"static' area base (if any) as defined in Part I of this 
document. Register Rl addresses the user's argument list 
(that is, Rl is preserved across the LINK). Any user 
program exception exit previously set by SVC PCEXIT is 
eliminated, but is restored when an UNLINK is issued to 
return to the LINKed-from program. 


If the specified file exists but is not a program file, the 
file, library, and volume names are pushed onto the stack 
and LINK initiates execution of the system's Procedure 
Interpreter, which then attempts to interpret the file as a 
procedure. 
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Operand Descriptions 


EP= 


EPLOC= 


LIBRARY= 


VOLUME= 


SYSTEM 


NOFAIL 


A name of up to eight characters, enclosed in 
quotes, which is used in conjunction with the 
current program library name (as a member name 
in that library) to form a complete file name, 
which is then sought and the corresponding file 
invoked as a program if found. If not found, 
the supplied name is used in conjunction with 
the system library name, and the resulting file 
name is sought. 


A byte address, which must not be in a user's 
program segment (segment 1), at which there is 
a character string of length eight giving the 
name of the member to be concatenated with the 
current program library name or system library 
name (as for the EP= operand). This must be 
specified in a form allowable in the D2(B2) 
fields of the SS-type assembler instruction 
format. 


A byte address at which there is a character 
string of length eight giving the overriding 
user program library name for use on this LINK 
and LINKs nested below this link, or a 
character literal in single quotes giving this 
name. The previous default library name 
becomes effective again upon UNLINK to this 
LINK issuer. 


Name of volume containing the overriding user 
program library, specified as for the LIBRARY 
operand. 


Specifies that the user's program library is 
not to be searched for the requested member. 
Only the system library is searched. 


Specifies that the program is not to be 
terminated by the CANCEL SVC in the event that 
the requested program is not found, or cannot 
be acquired or executed, but rather that 
control is to be returned to the address of the 
LINK SVC instruction plus six bytes (next 
sequential instruction address plus four). 
This option is intended primarily for Command 
Processor use. A code is returned in the top 
word of the stack to indicate the specific 
error condition (see LINK SVC description). 
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LINK 


LOADONLY 


Examples 


LAB1 
+LAB1 
+ 
+LG001 
+LG002 


LAB2 
+LAB2 
+ 
+ 
+ 


Specifies that after the new program or 
subprogram has been made addressable in segment 
1, and all initialization of segment 2 areas 
(including the Link Return List) has been 
accomplished, control will be returned to the 
address of the LINK SVC plus 10 bytes, instead 
of being passed to the new program. The new 
program's entry point address will be in 
register zero when control is returned to the 
LINK issuer. The LINK SVC must be issued from 
segment 0 if this option is to be used. 


LINK EP='PROG1' 
PUSHC = 0(16) ,LGO01 


B LGOO2 
DC X'00' ,CL8'PROG1' ,XL7'0O' 
svc 4 (LINK) 


LINK EPLOC=PNAME , SYSTEM 


PUSHN 0,16 

MVI 0(SP) ,B'10000000' FLAG BYTE 
MVC 1(8,SP) ,PNAME PROGRAM NAME 
SVC 4 (LINK) 
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Supply Program Parameters 


Syntax 


(1) [label] LINKPARM PUT, 


» PRNAME= 


»REFERLABEL= 


[ ,REPEAT= 


(2) [label] LINKPARM CLEANUP [,REFERLABEL= 
[ 


C 


(3) [label] LINKPARM REFER 


»MERGE [, REMOVE ] ,FMTLIST= 


»NOMERGE »REFERLABEL= 


Restrictions 


None. 
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{DISPLAY} 
{ENTER } 


‘string’ 


{address } 
{'string’ } 
{ (register) } 


{address } 
{ (register) } 


{address }] 
{'string' }] 
{ (register) }] 


{ENTER} ] 
{1-32 } ] 


{address }] 
{'string' }] 
{ (register) }] 


{address }] 
{'string' }] 


{ (register) }] 
{NO }] 
{YES }] 


{address }] 
{'string' }] 
{ (register) }] 


{address } 
{ (register) } 


{address } 
{'string' } 
{ (register) } 


LINKPARM 


Function 


The LINKPARM macro accesses the functions of the PUTPARM SVC (SVC 
33). The primary function (the PUT function) is to _ supply 
parameters to another program's GETPARMs before issuing the LINK 
SVC to invoke that program. The second function (the CLEANUP 
‘function) is to deallocate the various internal data structures 
created by the PUT function. The third function (the REFER 
function) is to allow the calling program access to any parameters 
Which the user may have changed at GETPARM time (the MERGE 
option), or to return the address of a previously created and 
labelled FMTLIST (the NOMERGE option). See the PUTPARM SVC 
description for further detail on each of these functions of the 
PUTPARM SVC. 


Note that both the PUTPARM macro and the LINKPARM macro call _ the 
PUTPARM SVC (SVC 33). ##The PUTPARM macro allows only the 
parameterization of another program (the PUT function), while the 
LINKPARM macro accesses all the functions of the PUTPARM SVC. 
Users of the PUTPARM macro are encouraged to use the LINKPARM 
macro because of the more extensive functionality. The PUTPARM 
macro is kept for compatibility with existing programs. 


Operand Descriptions 


PUT Enables a program to supply parameters to a GETPARM 
issued by another program. The parameters to be 
supplied to the GETPARM are contained in a format list 
(FMTLIST) , created with the FMTLIST macroinstruction. 
The program issuing the LINKPARM PUT must link via the 
LINK SVC to the program issuing the GETPARM. A 
program may not use LINKPARM PUT to pass parameters to 
its own GETPARM. 


DISPLAY If DISPLAY is specified, requests a workstation 

ENTER transaction when the FMTLIST supplied to the linked-to 
program is accessed. If ENTER is specified, 
suppresses a workstation transaction when this FMTLIST 
is accessed. The default is ENTER. 


PRNAME= A name of up to 8 alphanumeric characters which 
identifies the PRNAME to be associated with the 
FMTLIST being supplied to the linked-to program or the. 
new PRNAME to be used if this is a backward 
reference. Specified as a character string in quotes. 
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REFERLABEL= 


FMTLIST= 


AID= 


PFKEY= 


LABEL= 


LINKPARM 


A name of up to 8 alphanumeric characters which 
identifies a previously labeled FMTLIST. This 
parameter is used to “backward reference" a previously 
created FMILIST. The backward reference facility 
allows a program to reuse the (possibly updated) 
parameters of a labelled FMTLIST. (See PUTPARM SVC 
description for further detail regarding backward 
reference facility). Specified as an expression 
addressing an 8-byte field containing the name of the 
FMTLIST, as a register in parentheses pointing to an 
8-byte field containing the name of the FMTLIST, or as 
a character string in quotes which is the name of the 
FMTLIST. Note that, for the PUT function, REFERLABEL= 
and FMTLIST= are mutually exclusive . For the CLEANUP 
function, REFERLABEL= specifies a particular FMTLIST 
to be deallocated. For the MERGE option, REFERLABEL= 
contains the name of the source FMTLIST, while 
FMTLIST= is the address of the destination FMTLIST. 


The address of the FMTLIST to be used. The FMTLIST 

is created by the FMTLIST macro. (See the FMTLIST 
macro description for further detail). Optionally the 
address of a KEYLIST+8 may be supplied. Specified as 
an expression addressing a FMITLIST, or as a register 
in parentheses containing the address of the FMTLIST. 
Note that, for the PUT function, REFERLABEL= and 
FMTLIST= are mutually exclusive. 


The AID (Attention ID) character of a PFkey to be 
passed to the GETPARM. AID characters are ‘A‘-'‘P' 
(i.e., PFkeys 1-16, respectively), ‘a'-'‘p' (i.e., 
PFkeys 17-32, respectively), and '@' (i.e., the ENTER 
key). Specified as an expression addressing a 
one~byte field containing the AID character, as a 
register in parentheses pointing to a one-byte field 
containing the AID character, or as a character string 
in single quotes which is the AID character. Note 
that AID= and PFKEY= are mutually exclusive. 


A PFkey to be passed to the GETPARM. PFKEY= may be 

a number from 1 through 32, or the word ENTER. PFKEY= 
must be a character string not in quotes. Note that 
PFKEY= and AID= are mutually exclusive. 


A FMTLIST may be labelled for later use by the 

backward reference and override facilities. (See 
PUTPARM SVC description for further detail.) A name 
of up to 8 alphanumeric characters is used to label 
the saved FMTLIST. May be specified as an expression 
addressing an 8-byte field containing the label, or as 
a register pointing to an 8-byte field containing the 
label. 


4-57 


LINKPARM 


REPEAT= 


CLEANUP 


REFER 


MERGE 


NOMERGE 


REMOVE 


Normally, no two GETPARM requests access the same 
FMTLIST. A FMTLIST may be declared to be for repeated 
use via the macro parameter REPEAT=. If REPEAT=NO (or 
is missing), the FMTLIST will be used only once. If 
REPEAT=YES, the FMTLIST will be used until it is 
removed. If REPEAT=n, the FMTLIST will be used ntl 
times (initial use + n repeats). May also be 
specified as an expression addressing a 2-byte binary 
repeat count or as a register in parentheses pointing 
to a 2-byte binary repeat count. The value of the 
repeat count can range from 1-32768. 


If CLEANUP is specified, the various internal 

structures created by the PUT function are 
deallocated. If no REFERLABEL is provided, all 
FMTLISTs created at this level and above are removed. 
If a REFERLABEL is provided, only the labeled FMTLIST 
will be removed. If the CLEANUP option is’ used, 
REFERLABEL is the only other parameter which may be 
suppplied. 


Allows previously created and used FMTLISTs at the 
current link level to be accessed. 


The MERGE option of the REFER function allows the 
“merging” of an updated 'used' labelled FMTLIST with a 
program-designated FMTLIST in the user's address 
space. The contents of the FMTLIST addressed by 
REFERLABEL= (the source) are merged into the FMTLIST 
addressed by FMTLIST= (the destination). Fields which 
are present in the source, but not in the destination, 
are ignored. Fields present in the destination but 
not in the source are left unchanged. 


Requests LINKPARM to return the address (in the 

Segment 2 buffer) of the FMTLIST referenced by the 
REFERLABEL= operand (i.e., a previously created and 
labelled FMTLIST). The address is returned on the 
Stack. 


Requests LINKPARM to remove (CLEANUP) the source 


FMTILIST after performing the merge. This option is 
only available with MERGE. 
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LINKPARM 


LINKPARM PUT ,DISPLAY ,PRNAME='OLDPRNAM' ,FMTLIST=FMTL1, 
LABEL='FOO1' ,AID='A' 


PLACE HOLDER FOR LABEL 
FMTLIST LABEL 

PRNAME 

UNUSED 

FMTLIST 

AID CHARACTER 

INITIAL FLAG BITS 
DISPLAY FLAG 


LINKPARM PUT ,PRNAME='NEWPRNAM' ,REFERLABEL=‘ FOO1" ,PFKEY=1 


PLACE HOLDER FOR LABEL 
NULL LABEL FOR FMTLIST 
PRNAME 

REFERLABEL 

INITIAL FLAG BITS 

AID CHARACTER 


LINKPARM REFER ,NOMERGE ,REFERLABEL='FOO1' 


Examples 
LAB1 

+LAB1l DS OH 

+ PUSHC 0(8) ,=CL8'FOO1' 

+ PUSHC 0(8) ,=CL8'OLDPRNAM' 

+ PUSHA 0,0 

+ PUSHA FMTL1 

+ MVI FMTL1,C‘A‘ 

+ PUSHA 0,0 

+ OI 0(15) ,x'"80' 

+ SVC 33 (PUTPARM) 
LAB2 

+LAB2 DS OH 

+ PUSHC 0(8) ,=CL8'' 

+ PUSHC 0(8) ,=CL8'NEWPRNAM'‘ 

+ PUSHC 0(8) ,=CL8'FOO1' 

+ PUSHA 0,0 

+ MVI 1(15) ,65 

Se SVC 33 (PUTPARM) 
LAB3 

+LAB3 PUSHC 0(16) ,=CL16'' 

+ PUSHC 0(8) ,=CL8'FOOL' 

+ PUSHA 0,0 

+ OI 0(15) ,x'40' 

+ SVC 33 (PUTPARM) 
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NULL LABEL AND PRNAME 
REFERLABEL 

INITIAL FLAG BITS 
REFER FLAG 


Log Off Interactive Terminal 


Syntax 


[label] LOGOFF 


Function 


The LOGOFF macroinstruction generates the code to issue the 


appropriate SVC call and parameter list to effect a 


program request." 


Operand Descriptions 


No operands are required. 


Example 


LOGOFF 

PUSHA 0,0 
PUSHA 0,0 
svc 43 


NULL 
PARAMETERS 
(LOGOFF) 
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"logoff by 


Mount Disk or Tape Volume 


Syntax 
(1) [label] MOUNT DISK= 
»LABEL= 
»VOLTYPE= 
»NSA= 
(2) [label] MOUNT TAPE= 
,LABEL= 
»NOMESSAGE= 
Restrictions 
None. 
Functions 


1) To request the mounting of a disk volume on_ the 


{ (register) } 
{integer } 
{address } 


{SL } »BLP= {NO } 
{NL } {YES} 
{R} ,SPOOL= {NO } 
{F} {YES} 
{NO } ,NODISPLAY= {NO } 
{YES} {YES} 


{ (register) } 
{integer } 
{address } 


{AL } ,BLP= {NO } 
{NL } {YES} 
{IL } 
{NO } 
{YES} 


,VOLUME= { (register) } 


{'string’ } 
{address } 


,USAGE= 


»WORK= 


»NOMESSAGE= 


,»VOLUME= { (register) } 


{*string' } 
{address } 


USAGE= 


indicated 


device with the specified label, usage, type, SPOOL file, 
and Work file attributes. 


2) To request the mounting of a tape volume on the 


device with the 
attributes. 


MOUNT issues a return code to the user program in the 


word which 
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indicated 


indicated device with the specified label 


stack top 


indicates the success/failure/status of the operation 
(see MOUNT SVC description). 


MOUNT 


Operand Descriptions 


DISK= 


TAPE= 


A number between 0 and 255 which is the system-defined 
device number of the disk unit on which the volume is to 
be mounted. 


A number between 0 and 255 which is the system defined 
device number for the tape unit on which the volume is to 
be mounted. 


DISK and TAPE may be specified as a register in 
parentheses containing the device number in binary in its 
low-order position, as an integer not in quotes which is 
the device number in decimal, or. as an expression 
addressing a one-byte field containing the device number 
in binary. One of these operands is required and they 
are mutually exclusive. 


VOLUME= The name of the volume which is to be mounted. It may be 


specified as a register in parentheses pointing to the 
volume name, as a character string in single quotes which 
is the volume name, or as an expression addressing a 
6~byte field containing the volume name. This operand is 
required. 


***THE FOLLOWING OPERANDS ARE OPTIONAL**<* 


BLP= 


LABEL= 


USAGE= 


This operand instructs the system to bypass label 
processing/checking and should be specified with care. 
Valid values are YES and NO. The default is to NO. 


Denotes the type of volume label present on a volume. 
Valid values are: 


SL - Standard WANG VS labels. 

NL - No labels are present on the volume. 
AL - Standard ANSI-type labels. 

IL - Standard IBM-type labels. 


The default for a disk volume is to SL; for a tape 
volume the default is to AL. Note that SL is valid for 
disk volumes only and that AL and IL are valid for tape 
volumes only. 


Denotes volume access and dismounting restrictions. Note 
that dismounting restrictions also apply to remounting 
with different attributes. Valid values are: 


SH - Shared: Volume may  ~»be accessed and 
dismounted by any user. 
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MOUNT 


RR - Restricted Removal: Volume may be accessed 
by any user but dismounted by the mounting 
user only. 


PR ~- Protected: Files on the volume may. be read 
by any user but updated and dismounted by the 
mounting user only. 


EX - Exclusive: Volume may be accessed and 
dismounted by the mounting user only. 


Default is to SH for both disk and tape volumes. RR and 
PR are valid for disk volumes only. 


VOLTYPE= Denotes the type of disk volume being mounted as 
either fixed or removable. Valid values are F and R 
respectively, with the default being to R. This operand 
is valid for disk volumes only. 


SPOOL= Denotes whether the volume is to be included in the list 
of volumes scanned when the system creates a SPOOL 
(Print) file for a user whose values are YES and NO, with 
the default being to NO. This operand is valid for disk 
volumes only. 


WORK= Denotes whether the volume is to be included in the list 
of volumes scanned when the system creates a Work file 
for a user whose default work volume has not been SET. 
Valid values are YES and NO, with the default being to 
NO. This operand is valid for disk volumes only. 


NSA= If YES is specified, indicates that the volume to be 
mounted follows non-standard addressing conventions 
(soft-sectored diskette only). The default is to NO. 


NODISPLAY= If YES is specified, indicates that no messages 
are to be displayed on the user's workstation; the 
operator console messages must be used to coordinate 
physical mounting. The default is to NO. 


NOMESSAGE= If YES is specified, indicates that the volume to be . 
mounted is already on the disk or tape drive. No MOUNT 
message will be displayed, and the Volume Control Block 
(VCB) information is updated from the volume label. The 
default is to NO. 


4-63 


Examples 

LAB MOUNT DISK=(R1) , VOLUME='SYSTEM' , LABEL=SL , USAGE=SH, 
VOLTYPE=F , SPOOL=NO ,WORK=YES 

+LAB PUSHN 0,8 GET TWO WORDS ON THE STACK 

+ STC R1,1(,15) SET DEVICE NUMBER 

+ MVC 2(6,15) ,*+10 SET VOLUME NAME 

+ B *+10 BRANCH AROUND CONSTANT 

+ DC CL6'SYSTEM' VOLUME NAME 

+ MVI 0(15) ,B'00010001' SET FLAGS 

+ svc 30 (MOUNT) ISSUE SVC 

LAB MOUNT DISK=DISKVOL , VOLUME= (R4) 

+LAB PUSHN 0,8 GET TWO WORKDS ON THE STACK 

+ MVC 1(1,15) ,DISKVOL SET DEVICE NUMBER 

+ MVC 2(6,15) ,0 (R4) SET VOLUME NAME 

+ MVI 0(15) ,B'00000000' SET FLAGS 

+ SVC 30 (MOUNT) ISSUE SVC 

LAB MOUNT TAPE=28 , VOLUME=TAPEVOL , LABEL=IL , USAGE=EX 

+LAB PUSHN 0,8 GET TWO WORDS ON THE STACK 

+ MVC 0(1,15) ,*+10 SET DEVICE NUMBER 

+ B *+6 BRANCH AROUND CONSTANT 

+ DC AL1 (28) DEVICE NUMBER 

+ MVC 2(6,15) , TAPEVOL SET VOLUME NAME 

+ MVI 0(15) ,B'01010000' SET FLAGS 

+ SVC 30 (MOUNT) ISSUE SVC 
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Generate Display Message 


Syntax 


[label] MSGLIST msg#,issuer,'message-segment-1' 
[,'message-segment-2',...] 


Restrictions 


Intended for use in conjunction with the GETPARM and CANCEL 
macroinstructions. See those macroinstructions and _ the 
corresponding Supervisor Call descriptions. 


Function 


Generates a data structure suitable for use as the object of 
"MSG=' operands of the GETPARM and CANCEL macroinstructions. 


Operand Descriptions 


ms g# Up to four characters enclosed in 
single quotes, normally a message 
number, to be displayed with the 
message. The msg # is displayed on 
row 1 of the workstation screen. 


issuer Up to six characters enclosed in 
single quotes, normally an 
identification of the issuing 


routine, to be displayed with the 
message. The issuer is displayed on 
row 1 of the workstation screen. 


‘message-segment-n' Message text in single quotes to be 
displayed on a single line. May be 
repeated as often as required, to 
define additional lines to be 
displayed. No line may be over 79 
characters long. The message may 
contain single quotes (apostrophes). 
Message text is displayed beginning 
on row 3 of the workstation screen. 


Example 
LAB1 MSGLIST '123' ,{ISSUER','LINE 1°,'LINE 2' 
+LAB1 DC CL4,'123' 
+ DC CL6' ISSUER‘ 
+ DC AL2 (6+6+1) 
+ DC C'LINE 1' 
+ DC X'OD' NEW LINE 
+ DC 


C'LINE 2' 
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Open a File 


Syntax 


[label] OPEN UFB= { (register) } 
{expression} 


[,MODE= {OUTPUT}] 
{INPUT } 
{10 } 
{EXTEND} 
{ SHARED} 


{ ,{NOGETPARM} ] 
{NODISPLAY} 


[,EXIT= { (register) }] 
{absolute expression} 


[,PLOG= {YES }] 
{ NO } 


Restrictions 
None. 
Function 


Prepares a file for processing by Data Management System 
functions. The User File Block (UFB) is normally created 
prior to OPEN by means of the UFBGEN macroinstruction. The 
OPEN macroinstruction includes provision for optional 
modification of the ‘Open mode‘ flags of the UFB. If the file 
was already open to the issuing task, no additional OPEN 
processing occurs. In this case the file remains open in the 
mode specified in the Open File Block addressed by this UFB. 


Operand Descriptions 


UFB= The address of a User File Block, which must be 
specified either as a register designation in 
parentheses, where the register is assumed to 
contain the UFB address, or as a UFB address 
expression not in parentheses. If omitted, 
only the MVI for open mode modification and the 
SVC instruction will be generated. 


MODE= Specifies a value to be placed in the UFB_ to 
designate an open mode. This is done before 
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NOGETPARM 


NODISPLAY 


OPEN 


the OPEN Supervisor Call is issued. This 
operand is optional. 


Causes a GETPARM type "RD'' to be issued rather 
than a type "I". This suppresses user 
interaction and causes procedure-supplied 
parameters to be ignored. This option should be 
used only when run-time parameters have already 
been obtained through a program-issued GETPARM. 
In this case, the programmer should also use the 
OPEN exits which enable the program to handle 
error conditions. 


Causes a GETPARM type "ID" to be issued rather 
than a type "I". This suppresses user 
interaction as long as the values supplied in 
the UFB or through a procedure are not lexically 
in error. 


NOTE : 


User interaction will occur even with the NOGETPARM or 
NODISPLAY options if a field is semantically in error 
(e.g., an invalid device type). 


EXIT= 


PLOG= 


A value indicating which file assignment 
problems should cause control to be returned to 
the issuing program rather than cause generation 
of a user interaction via a GETPARM (Type "R"). 
See description of OPEN SVC for possible 
values. May be specified as a register 
designation in parentheses, or as an absolute 
expression not in parentheses. The value in the 
low-order byte of the register, or the value of 
the expression, is stored in the high-order byte 
of the OPEN parameter word on the stack. 


If YES is specified, a file prologue will be 
created when the file is OPENed. Valid only for 
Word Processing files. This operand must be 
specified when the file is OPENed in OUTPUT mode 
(MODE=OUTPUT) in order for the file prologue to 
be identified with the file to be created. The 
default is to NO. 


OPEN UFB=(R2) ,MODE=INPUT 

MVI 44(R2) ,X'20' INPUT MODE 
PUSH 0,R2 

SVC 0 (OPEN) 


Modify Program Exception Exit Status 


Syntax 


1. {label] PCEXIT SET, [(list) ,ADDRESS={ (register) }] 


{expression}] 


2. [label] PCEXIT {RESET } 


{CANCEL} 


where 'list' may contain any of the following, separated by 


commas ¢ 


OP 
PO 
EX 
PR 
AD 
SP 
DA 


DD 
SR 
SO 
FPO 
FPU 
SI 
FPD 


Operation 

Privileged Operation 
Execute 

Protection 

Addressing 
Specification 

Data 

Fixed Point Overflow 
Fixed Point Divide 
Decimal Overflow 
Decimal Divide 
Supervisor Call Range 
Stack Overflow 

Floating Point Overflow 
Floating Point Underflow 
Significance 

Floating Point Divide 


To specify that all types of program exception interrupts 
are to be intercepted, specify ‘ALL' instead of a ‘list'. 


Function 


SET 


RESET 


CANCEL 


To specify user-program exception handling for 
the listed program interruptions. The previous 
program exception handling status, if any, is 
saved for use by the RESET function. 


Restores user~program exception handling status 
to its state before the most recent SET 
function, if there was a 'PCEXIT SET' issued in 
the current program. The most recent status is 
discarded. 


Removes all user-program exception handling in 
the current program (since a LINK from another 
program or Command Processor program 
initiation). All such status is discarded. 
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PCEXIT 


Operand Descriptions 


ADDRESS= 


See 


above 


This and the '(list)' operand may be specified 
only with the '‘'SET' operand. A_ register 
specification in parentheses signifies that the 
register contains the exit address. An 
expression not in parentheses is evaluated to 
the exit address directly. 


for other operand descriptions and '‘list' 


suboperand descriptions. 


Example 
LAB1 


PCEXIT SET, (FPU,SI) ,ADDRESS=(R1) 


PUSHC 0(4,0) ,*+10 

B *+8 

DC BL4 '0000000000000000110'° LIST 
PUSH 0,R1 EXIT ADDRESS 

MVI O(SP) ,0 SET 

SVC 31 (PCEXIT) 
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Protect a Disk File 


Syntax 


{label] PROTECT PLIST = {expr } 


{ (reg) } 


{ 

{ 

{ 

{ { LIBRARY } » LIBRARY=expr 
{ { FILE=expr } 

{ ,VOLUME=expr 
{ [ ,OWNER=expr] 
{ 
{ 


{ ,FILECLAS=expr] 


[ , {RETPD=expr }] 
[ {EXPRDT=expr}] 


[,RESTRICT= NO ] 
[ YES ] 


Function 


To update the protection information (protection class, owner of 
record, and/or expiration date) for a disk file or a library of 
disk files on a volume. The structure of the Volume Table of 
Contents (VIOC) is not affected by the change. No file that is 
to have its protection information modified may be open when the 
PROTECT is attempted. 


Return codes in binary in the top word of the stack indicate the 
result of the request: 


Return Code 
Return Code 
Return Code 
Return Code 
Return Code 
Return Code 
Return Code 


on 
oO 
I 


Protection status successfully changed 

4 - Volume not mounted 

8 - Volume used exclusively by other user 

12 - All buffers in use, no protection change 

16 - Library not found 

20 - File not found 

24 - Update access denied, no protection 
change 

28 - (unused) 

32 ~ File in use, no protection change 

36 - VIOC error! FDX1 & FDX2 don't agree 

VTOC error! FDX2 & FDR don't agree 

44 - Invalid argument list address 

48 - I/O error: VTOC unreliable? 

52 - Open or protected files bypassed in 
protecting library 

Return Code = 56 - Invalid new protection data 


Return Code 
Return Code 
Return Code 
Return Code 
Return Code 
Return Code 
Return Code 


ib hk ut uo op 
> 
(a) 
1 


Note: If the PLIST= option is not utilized, it is the program's 
responsibility to pop 32 bytes off the stack beyond the 
return code word on the stack. 
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PROTECT 


Operand Descriptions 


PLIST= 


LIBRARY 


FILE= 


LIBRARY= 


VOLUME= 


OWNER= 


FILECLAS= 


The address of a PROTECT parameter list. (For 
a description of the format of the parameter 
list, please refer to the description of the 
PROTECT SVC in Chapter 6.) If PLIST= is 
specified, no other operand may be specified. 
If PLIST= is not specified, the macro generates 
code to dynamically build a parameter list on 
the stack prior to issuance of the PROTECT SVC. 


Indicates that the protection attributes of all 
files within the library specified are to be 
modified. Use of this operand is mutually 
exclusive with the FILE= operand. 


Specifies the address at which the file's name 
is located. May be specified as a character 
string delimited by single quotes, in which 
case, a constant is assumed. Use of this 
operand is mutually exclusive with the LIBRARY 
operand descrbed above. 


Specifies the address at which the library's 
name is located. May be specified as a 
character string delimited by single quotes, in 
which case, a constant is assumed. This 
operand is required if PLIST= is not specified. 


Specifies the address at which the volume's 
name is located. May be specified as a 
character string delimited by single quotes, in 
which case, a constant is assumed. This 
operand is required if PLIST= is not specified. 


If specified, indicates that the 3 byte "Owner 
of Record" protection attribute is to be 
modified and the address at which the new value 
is located. May be specified as a character 
string delimited by single quotes, in which 
case, a constant is assumed. 


If specified, indicates that the 1 byte "File 
Class" protection attribute is to be modified 
and the address at which the new value is 
located. May be specified as a character 
string delimited by single quotes, in which 
case, a constant is assumed. 
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PROTECT 


EXPRDT= 


RETPD= 


RESTRICT= 
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If specified, indicates that the "Expiration 
Date" protection attribute is to be modified 
and the address at which the new value (3 byte 
packed decimal, YYDDD+) is located. May be 
specified as a character string delimited by 
single quotes, in which case a constant is 
assumed. Use of this operand is mutually 
exclusive with use of the RETPD= operand. 


If specified, indicates that the "Expiration 
Date" protection attribute is to be modified 
and the address at which a “Retention Period," 
in terms of days (3 byte packed decimal, 
OODDD+) is located. May be specified asa 
character string delimited by single quotes, in 
which case a constant is assumed. Use of this 
operand is mutually exclusive with use of the 
EXPRDT= operand. 


If NO is specified, or the operand is omitted, 


the PROTECT operation precedes utilizing 
current file access rights. If YES is 
specified, the operation is restricted, 


assuming only the file access rights of the 
user, ignoring any special access rights of the 
program. 


PROTECT FILE=PROFILE , LIBRARY=PROLIBR , VOLUME=PROVOLUME, X 


OWNER='"DOV' , FILECLAS=PROCLAS ,RETPD=PRORETPD 


PUSHA 0,0 

PUSHA 0,0 

MVC 3(3,15) ,PRORETPD 
MVC =: 0(3,, 15) ,=CL3DOV' 
PUSHN 0,8 

MVC 7(1,15) ,PROCLASS 
MVI 6(15) ,B'00001111' 
MVC 0(6,15) ,PROVOLUME 
PUSHC 0(8) ,PROFILE 
PUSHC 0(8) ,PROLIBR 

SVC 42 (PROTECT) 
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RETENTION PERIOD 
FILE OWNER OF RECORD 


FILE CLASS 
VOLUME 


FILE 
LIBRARY 


Supply Program Parameters 


Syntax 
[label] PUTPARM [ DISPLAY ] 
[ ENTER ] 
» PRNAME = ‘literal' 
» FMTLIST = { (register) } 
{ expression } 
[,LABEL = 'literal'] 
Restrictions 
None. 
Function 


PUTPARM enables a program to supply parameters to a GETPARM 
issued by another program. The PUTPARM issuer must dynamically 
link to the program issuing the GETPARM via the LINK SVC. (A 
program may not use PUTPARM to parameterize its own GETPARMs.) 


The parameters to be supplied to the GETPARM are contained 
in a format list (FMTLIST), created with a FMTLIST 
macroinstruction. When PUTPARM is issued, it verifies that the 
specified FMTLIST is in the proper format, then saves it in a 
Segment-2 buffer area for subsequent GETPARM use. PUTPARM also 
constructs a Parameter Reference Block (PRB) to save the label, 
PRNAME, display option, and certain other information. 


When a GETPARM in the linked-to program is issued, it 
searches through the FMTLISTs in the Segment-2 buffer area. If a 
FMTLIST is found whose PRNAME matches the PRNAME of the GETPARM's 
KEYLIST, the FMTLIST parameter values are copied to the KEYLIST, 
thus supplying the required GETPARM parameters. A workstation 
transaction is suppressed if the 'ENTER' option is selected; 
otherwise, a GETPARM screen is displayed. PUTPARM returns to the 
issuer eight bytes of output on the top of the stack: 


Bytes 0-3 return code 


0 success 
8 Bad FMILIST supplied to this SVC 
12 Error detected in previously constructed 


parameter reference blocks. 
Bytes 4-7 Address of FMTLIST saved for GETPARM 
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PUTPARM 


Operand Descriptions 


DISPLAY 

ENTER requests GETPARM to display or bypass 
displaying the screen. 

PRNAME= A name of up to 8 alphanumeric characters 
enclosed in quotes, identifying the PRNAME of 
the FMTLIST. 

FMTILIST= The address of the FMTLIST in the _ format 
specified in GETPARM SVC. (See the FMILIST 
macroinstruction.) 

LABEL= A name of up to 8 alphanumeric characters 
enclosed in quotes. The label of _ this 
parameter reference block to be used by GETPARM. 

Examples 
LAB1 PUTPARM ENTER,PRNAME=‘ABCDE' x 


»FMTLIST=ADDR1 , LABEL='XYZ' 


LAB PUTPARM PRNAME='ABCDE' ,FMTLIST=(R2) 
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Read a Record 


Syntax 


[ ]* 
[label] READ |HOLD UFB={ (register) } [,COND=number] 


| 

3 

{REL | {expression} 

| KEYED | 

| NODATA | 

| TABS | 

| MOD | 

| ALTERED | 

| CONNECTPARM | 
| 
J 


| STATUS 


(* Various combinations in parentheses are allowed. See 
below.) 


Function 


To read a record from any file or device for which READ is 
supported by the Data Management System. This includes the 
special workstation READ functions (READ TABS, READ MOD). 
The function of the READ macroinstruction depends on the 
value of its first operand. Valid first operands for 
various device and file types are as follows: 


. Fixed Length Consecutive disk files - omitted 
HOLD 
(HOLD ,NODATA) 
REL 
(REL , HOLD) 
(REL ,NODATA) 
(REL ,HOLD ,NODATA) 


. Variable Length Consecutive disk files - omitted 
HOLD 
(HOLD ,NODATA) 


‘ Indexed disk files —- omitted 
HOLD 
(HOLD ,NODATA) 
KEYED 
(KEYED , HOLD) 
(KEYED ,NODATA) 
(KEYED ,HOLD ,NODATA) 


és Telecommunications - omitted 


CONNECTPARM 
STATUS 
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. Workstation files - {omitted } treated 
{REL } identically 
{MOD } treated 
{ (MOD ,REL) } identically 
{ALTERED } treated 


{ (ALTERED ,REL)} identically 
TABS 


A file must have been opened in modes INPUT, IO or SHARED, 
or placed in temporary IO mode by the ‘START I10' function, 
before attempting to READ the file. The record or 
workstation line, fields, or tab position indications are 
returned in the user's record area, as addressed by field 
UFBRECAREA of the UFB. For 'READ REL' or any workstation 
READ other than 'READ TABS', the records number within the 
file, or line number on the screen (from 1) to be read is 
taken from the word addressed by field UFBKEYAREA of the 
UFB. For ‘READ KEYED', the key value is taken from the 
memory area beginning with the byte addressed by 
UFBKEYAREA, and extending for the number of bytes specified 
by UFBKEYSIZE. Descriptions of the functional effects of 
the various allowable suboperands (HOLD, REL, KEYED, 
NODATA, TABS, ALTERED, MOD) may be found in the Data 
Management System description (Part IV of this document) 
and in the operand descriptions below. 


Invalid key and end-of-data conditions on a READ result in 
return to the address in UFBEODAD with the normal return 
point address in register 0 and file status bytes (UFBFS1, 
UFBFS2) set to the following ASCII characters: 


10 - End of data 
23% Invalid key (no record found) on 'READ REL’ or 
"READ KEYED‘ 


Other exceptional and error conditions result in return to 
the address in UFBERRAD with the normal return point 
address in register 0 and file status bytes (UFBFS1, 
UFBFS2) set to the following ASCII characters: 


30 - Permanent I/O error 

34 - Order check on workstation 

95°= Invalid function sequence for block-level I/0 
96 - Invalid data area location or alignment 

of = Invalid length for device 

98 - Magnetic tape trailer label error (block count) 


If UFBEODAD contains binary zero, the address in UFBERRAD 
is used for invalid key and end-of-data returns. If it too 
is zero, these conditions and I/O errors cause program 
terminations. 


READ 


Operand Descriptions 


REL 


KEYED 


HOLD 


NODATA 


Indicates that the record or workstation line 
to be read is specified by the binary number 
(from 1) in the word addressed by UFBKEYAREA. 
Assumed for workstation files. 


Indicates that the record to be read from an 
indexed disk file is specified by the key value 
in bytes beginning at the address in 
UFBKEYAREA, and extending for the number of 
bytes specified in UFBKEYSIZE. The user's 
program should not modify UFBKEYSIZE. 


Indicates that the record read from a disk file 
may be rewritten by REWRITE. Must be specified 
in order to successfully complete a REWRITE of 
this record. For SHARED open mode, indicates 
that the record read from a disk file is not to 
be made available to any other simultaneously 
executing program which is sharing the file 
until either the record is rewritten, it is 
deleted, or another record in any shared file 
is read with HOLD requested. Note that this 
implies that a program may only HOLD one record 
at a time, no matter how many files are being 
shared. 


Indicates that the record requested is to be 
read from the file in the manner indicated by 
other suboperands (including the HOLD 
suboperand), but that the record is not to be 
placed in the user's record area as addressed 
by UFBRECAREA. The address of the record in 
the Data Management System buffer is placed in 
register 1. This option is not valid in SHARED 
open mode. 


Indicates that telecommunication line 
connection parameters are to be read. 


Indicates that telecommunication device status 
is to be read. 


Indicates that current tab settings for the 
specified workstation are to be placed in the 
fifth through fourteenth bytes of the user's 
record area as addressed by UFBRECAREA. Values 
are column numbers 1-80 in binary. Zeroes 
indicate unset tab positions. 
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MOD 


ALTERED 


UFB= 


COND= 


Examples 


Indicates that the modifiable fields within the 
specified workstation line are to be placed in 
their corresponding positions in the user's 
record area as addressed by §UFBRECAREA. 
Protected fields may or may not be read and 
placed in the user's record area, depending on 
the workstation model. If protected fields are 
not transferred, the corresponding positions in 
the user's record area are not changed. 


Indicates that only those fields with 
selected-field tags set are to be placed in the 
user's record area, in positions corresponding 
to their screen positions. Other data on the 
user's record area remains unchanged. Field 
attribute characters of altered fields have 
their selected-field tags set oon the 
corresponding field attribute characters in the 
user's record area. 


The address of a User File Block (UFB), which 
may be supplied as a register specification in 
parentheses, where the register contains the 
UFB address, or as an expression not in 
parentheses, where the word addressed is. 
assumed to begin the UFB. 


If specified, the number or absolute expression 
becomes the first operand oof the JSCI 
instruction by which the READ function is 
entered. READ is thus made conditional. 
COND=15 is the default. Register 1 is loaded 
with the UFB address even when the condition is 
not satisfied. 


READ (REL ,HOLD) ,UFB=(R3) 

LR 1,R3 SET REGISTER 1 
MVI 0(1) ,B'00000101' MODIFIERS 

JSCI 15,0(,1) READ FUNCTION 
READ UFB=UFBADDR 

LA 1 ,UFBADDR SET REGISTER 1 
MVI 0(1) ,B'00000000' MODIFIERS 

JSCI 15,0(,1) READ FUNCTION 


4~78 


Read File Descriptor Record(s) 


Syntax 


[label] READFDR PLIST={ (register) } 
{ address } 


[label] READFDR LIBRARY={ (register)}, FILE={ (register) }, VOLUME={ (register)}, 


{'string' } {"string' } {'string' } 
{ address } { address } { address } 
AREA={(register)} [,FDR={1  }] [ ,AALTLIB={ (register) }, 
{ address } {in } {'string' } 
{BOTH} { address } 
ALTVOL={ (register) }][,PLOG={NO }, PAREA= { (register) }] 
{"'string' } {YES } { address } 
{ address } {ONLY } 


Restrictions 


The area addressed by PLIST must not be in the user's 
segment one (re-entrant code segment). 


If any operand is specified by a string, the invoking user 
program must allow for the generation of a literal pool. 


With the exception of specification by character strings, 
specifications of libraries and files must reference 8-byte 
fields, those for volumes must reference 6-byte fields. 


Function 


Allows user programs to locate a disk file on the specified 
volume and copy its File Descriptor Record(s) (label) into 
the memory location denoted by the AREA operand; also reads 


a WP file prologue and returns the file prologue into the 
specified AREA. 


If PLIST is not specified, then operands FILE, LIBRARY, 
VOLUME, and AREA are required and the user program is 
responsible for popping 36 bytes (50 if ALTLIB’ is 
specified) beyond the FDR1 disk address word since the 
parameter list is dynamically built on the stack. 


If an alternate search library (ALTLIB) is specified, then 
the values of the LIBRARY and VOLUME are modified as 
required to indicate in which library the file was found. 


READFDR issues a return code to the user program in the 
stack top word which indicates the success/failure of the 
operation, and the disk address of the FDR1 in the next 


READFDR 


stack word (this address is usable only if the read was 
successful, i.e., the return code equals zero). (See 
READFDR SVC for return codes and address .) 


Operand Descriptions 


PLIST= 


LIBRARY= 


FILE= 
VOLUME= 


AREA= 


FDR= 


ALTLIB= 


ALTVOL= 


A user-generated parameter list as described in the 
READFDR SVC; specified as a register in parentheses 
pointing to the parameter list, or as an expression 
addressing the parameter list. If this operand is 
specified, then all other operands are ignored. 


The name of the primary library to be searched for the 
file in question; specified as a register in 
parentheses pointing to the library name, as a _ literal 
in single quotes which is the library name, or as an 
expression addressing a character string whose value is 
the library name. 


The name of the file in question. It may be specified 
as for LIBRARY above. 


The name. of the volume on which the primary library 
resides. It may also be specified as for LIBRARY above. 


A user receiving area for the obtained file descriptor 
record(s); 80 bytes if one FDR is requested and 160 if 
BOTH is specified. It may be specified as a register 
in parentheses pointing to the address of the receiving 
area, or as an expression addressing a 4-byte field 
containing the address of the receiving area. 


This optional operand indicates which FDR(s) to read. 
If omitted, the default is to 1 (read FDR1 only). 


| Read the FDRI1 only. 

n- Read the (n-1)th FDR2 only where "n" 
is integer 2 or higher. For 
example, ''3' reads the second FDR2. 

BOTH- Read both FDR1 and the first FDR2. 


The name of a library to be searched if the file in 
question cannot be located in the library specified by 
the LIBRARY operand. It may be specified as for 
LIBRARY above. This operand is optional. However, if 
specified, then ALTVOL must be specified as well. 


The name of the volume on which the alternate search 
library resides. It may also be specified as for 
LIBRARY above. This operand is valid only in 
conjunction with ALTLIB. 
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PLOG= If YES, then read the WP file prologue along with any 
other options set. If ONLY, then the caller wants only 
the file prologue to be read. If NO is specified, then 
the caller does not request the file prologue be read. 


If YES or ONLY is specified, then the caller must 
specify in the PAREA operand a receiving area for the 
file prologue. 


PAREA= Indicates the address of the receiving area for the 
file prologue. May be specified as a register in 
parentheses containing the address of the _ receiving 
area, or as an address expression pointing to a 
four~byte area containing the address of the receiving 
area. 


Examples 

LAB READFDR PLIST=(R4) 

+LAB PUSHA 0,0 GET ONE WORD OF ZEROES ON THE STACK 
+ PUSH 0,R4 POINT TO PLIST WITH STACK TOP WORD 
+ SVC 24 (READFDR) ISSUE SVC 


LAB READFDR LIBRARY='SYSLIB‘ ,FILE=(R1) ,VOLUME=SYSVOL ,AREA=FDRAREA ,X 
FDR=BOTH , ALTLIB='SYSLIB2' , ALTVOL=SYSVOL 


+LAB PUSHN 0,50 GET SPACE ON STACK FOR PLIST 

+ MVC 0(8,15) ,=CL8'SYSLIB' SET LIBRARY NAME 

+ MVC 8(8,15) ,O(R1) SET FILE NAME 

+ MVC 16(6,15) ,SYSVOL SET VOLUME NAME 

+ MVI 22(15) ,x'04' SET FLAG TO READ FDR1 AND 1ST FDR2 
+ MVI 23(15) ,x'00' (THIS FIELD NOT USED FOR FDR=BOTH) 
+ MVC 24(4,15) ,FDRAREA SET FDR RECEIVING AREA ADDRESS 

+ XC 28(8,15) ,28(15) (THIS FIELD RESERVED) 

+ OI 22(15) ,X'08' SET FLAG TO INDICATE ALTERNATES 

+ MVC 36(8,15) ,=CL8'SYSLIB2' SET ALTERNATE LIBRARY NAME 
+ MVC 44(6,15) ,SYSVOL SET ALTERNATE VOLUME NAME 

+ PUSHA 0,0 GET ONE WORD OF ZEROES ON THE STACK 
+ PUSHA 0,4(,15) POINT TO PLIST WITH STACK TOP WORD 
+ svc 24  (READFDR) ISSUE SVC 

LAB READFDR LIBRARY='USERLIB' ,FILE=(R1) , VOLUME=SYSVOL , AREA= (R6) 
+ LAB PUSHN 0,36 GET SPACE ON STACK FOR PLIST 

+ MVC 0(8,15) ,=CL8'USERLIB' SET LIBRARY NAME 

+ MVC 8(8,15) ,0(R1) SET FILE NAME 

+ MVC 16(6,15) ,SYSVOL SET VOLUME NAME 

+ MVI 22(15) ,x'00' CLEAR FLAGS 

+ MVI 23(15) ,O INDICATE READ FDR1 ONLY 

+ ST R6,24(,15) SET FDR RECEIVING AREA ADDRESS 

+ XC 28(8,15) ,28(15) (THIS FIELD RESERVED) 

+ PUSHA 0,0 GET ONE WORD OF ZEROES ON THE STACK 
+ PUSHA 0,4(,15) POINT TO PLIST WITH STACK TOP WORD 
+ SVC 24  (READFDR) ISSUE SVC 
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Read Volume Table of Contents 


Syntax {ATTRIBUTES} 
{EXTENTS  } 
[label] READVTOC OPTION = {LIBRARIES } 
{FILES } 
{BLOCKS } 


{,PLIST= {(register) }] 
[ { expression}] 


{,VOLUME= {(register) }] 
[ { expression}] 
[ {‘literal' }] 


[,LIBRARY= { (register) }] 


[ { expression}] 
[ {'literal' }] 
[,cOUNT= { (register) }] 

[ { number }] 

{[,START= {(register) }] 
[ { expression}] 
[ { 1 }] 
[ ,OFB= {(register) }] 
[ { expression}] 


Restrictions 


The area addressed by PLIST must be in the user's Segment 2. 
If any operands are supplied as 'literals' (and in some other 
cases), the user must allow for generation of a literal pool. 


Function 


Provides information from a Disk Volume Table of Contents 
(VTOC). Specific functions are described under OPTIONS. 


READVTOC issues a return code in the stack top word, 
indicating success, or the reason for failure, of the 
operation. 


If PLIST is not specified, space for the parameter list is 
obtained from the stack; the length of the area is returned 
in General Register 1 (whose previous contents are lost). 


If PLIST is specified, the designated area must be large 
enough to hold the desired output. 
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Operand Descriptions 


OPTION= 


PLIST= 


VOLUME= 


EXTENTS 


LIBRARIES 


BLOCKS 


One of the following, coded as shown, indicating 
Which type of information is desired. This 
operand is required, unless PLIST is specified. 


ATTRIBUTES - 1. VTOC extents in use. 


Number of unused blocks in VTOC. 


2. Number of Libraries on Volume. 
Number of Files on Volume. 


3. Number of Free Extents on Volume. 
Total size of Free Extents. 


4. Descriptions of om (m=COUNT) 
largest Free Extents from nth 
(n=START) Free Extent. 


Descriptions of m (m=COUNT) Free 
Extents from nth (n=START). Free 
Extent. 


Lists m (m=COUNT) Library names and 
number of Files in each Library 
listed, starting from nth (n=START) 
Library name. 


FILES - Lists m (m=COUNT) Filenames starting 


from nth (n=START) File in specified 
Library. 


Reads m (m=COUNT) consecutive VTOC 
blocks starting from nth (n=START) 
block in VTOC and copies into File 
specified by OFB=. 


An expression, or a register in parentheses, 
pointing to an area to be used as the READVTOC 
parameter list. If PLIST is specified, no OPTION 
is required, nor are any of the other operands 
(in this case, it is assumed that the user has 
placed values in the PLIST for operands that 
would otherwise have been required). 


An expression, a register in parentheses pointing 
to a 6-byte name, or a literal in single quotes, 
indicating the Volume from which VIOC information 
is desired. Required for all OPTIONs (unless 
PLIST is specified). 


READVTOC 


LIBRARY= An expression, a register in parentheses pointing 
to an 8-byte name, or a literal in single quotes 
indicating the Library about which  VTOC 
information is desired. Required when 
OPTION=FILES (unless PLIST is specified). 


COUNT= A number or a register in parentheses containing 
a number, indicating how many items (one or more) 
are requested (see OPTION descriptions). 
Required for all OPTIONS unless "PLIST" is 
specified. 


START= An expression, or a register in parentheses 
containing a number, indicating which item (see 
OPTION descriptions) is the first item 
requested. Required for all OPTIONs (unless 
"PLIST" is specified). START=1 is the default. 


OFB= The address, or a register in parentheses 
containing the address, of the Open File Block. 
The file specified must be open for output with 
enough space allocated to accommodate m VTOC 
blocks (as specified in BLOCKS). 


Return Codes 


0 - Requested operation performed. 


4 - Invalid argument PLIST address. 

8 - VOLUME not mounted. 
12 - VOLUME used exclusively by another user or job. 
16 - Insufficient buffer space to perform operation. 
20 - Invalid OPTION request. 


24 - LIBRARY not found. 
28 - VTOC error; FDX1 and FDX2 conflict. 
32 - Disk I/O error; VIOC not reliable. 


Examples 


FOOBAR READVTOC OPTION=ATIRIBUTES , VOLUME='VOLVO' ,COUNT=32 , START=(R8) 
+FOOBAR DS OH 


+ LA 1,222 SIZE OF PARAMETER LIST 

+ PUSHN 0,0(,1) SPACE FOR PARAMETER LIST 
+ MVC =8(2,15) ,=Y (32) SET COUNT FIELD 

+ MVI 6(15) ,0 INSERT OPTION BYTE 

+ STH  R8,10(15) SET START FIELD 

+ MVC 0(6,15) ,=CL6'VOLVO' MOVE IN VOLUME NAME 

+ PUSH 0,15 PARAMETER LIST TO STACK 
+ SVC 19 (READVTOC) ISSUE READVTOC SVC 
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READVTOC 


READVTOC OPTION=EXTENTS , VOLUME=VCBSER , COUNT= (7) 


DS OH 

LR 1,7 COPY COUNT 

MH 1,=Y (6) TIMES ELEMENT SIZE 

LA 1,4(,1) PLUS MINIMUM SECTION LENGTH 

PUSHN 0,0(,1) GET SPACE REQUIRED 

STH 7,8(15) SET COUNT FIELD 

MVI 6(15) ,1 INSERT OPTION BYTE 

MVC 10(2,15) ,=Y(1) SET START FIELD 

MVC 0(6,15) , VCBSER MOVE IN VOLUME NAME 

PUSH 0,15 PARAMETER ADDRESS TO STACK 

SVC 19 (READVTOC) ISSUE READVIOC SVC 

READVTOC OPTION=LIBRARIES , VOLUME= (6) ,COUNT=32 

DS OH 

LA 1,340 SIZE OF PARAMETER LIST 

PUSHN 0,0(,1) SPACE FOR PARAMETER LIST 

MVC 8(2,15) ,=¥ (32) SET START FIELD 

MVI 6(15) ,2 INSERT OPTION BYTE 

MVC 10(2,15) ,=Y(1) SET START FIELD 

MVC 0(6,15) ,0 (6) MOVE IN VOLUME NAME 

PUSH 0,15 PARAMETER LIST TO STACK 

svc 19 (READVTOC) ISSUE READVTOC SVC 

READVTOC OPTION=FILES , VOLUME='SYSTEM' , LIBRARY='SYSS' ,COUNT=16 

DS OH 

LA 1,148 SIZE OF PARAMETER LIST 

PUSHN 0,0¢,1) SPACE FOR PARAMETER LIST 

MVC 0(2,15) ,=Y (16) SET COUNT FIELD 

MVI 6(15) ,3 INSERT OPTION BYTE 

MVC 10(2,15) ,=¥ (1) SET START FIELD 

MVC 0(6,15) ,=CL6'SYSTEM' MOVE IN VOLUME NAME 

MVC 12(8,15) ,=CL8°SYSS' MOVE IN LIBRARY NAME 

PUSH 0,15 PARAMETER LIST TO STACK 

SVC 19 (READVTOC) ISSUE READVTOC SVC 

READVTOC OPTION=BLOCKS , VOLUME=VCBSER ,COUNT= (3) ,START= (4) , 
OFB=(ROFB) 

DS OH 

LA 1,20 SIZE OF PARAMETER LIST 

PUSHN 0,0(,1) SPACE FOR PARAMETER LIST 

STH 3,8(15) SET COUNT FIELD 

MVI 6(15) ,4 INSERT OPTION BYTE 

STH 4,10(15) SET START FIELD 

MVC 0(6,15) , VCBSER MOVE IN VOLUME NAME 

ST ROFB ,12(,15) SET OFB ADDRESS 

PUSH 0,15 PARAMETER LIST TO STACK 

SVC 19 (READVTOC) ISSUE READVTOC SVC 


READVTOC PLIST=(RLIST) ,START= 
DS OH 

PUSH 0,RLIST 

SVC 19 (READVTOC) 
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PARAMETER ADDRESS TO STACK 
ISSUE READVTOC SVC 


Register Equation 


Syntax 
REGS FP = {YES} 
{NO } 
Restrictions 
None. 
Function 


The REGS macroinstruction equates register numbers with the 
Standard symbolic names used by all other system 
macroinstructions which refer to general registers. It should be 
included in all program assemblies which make use of system 
macroinstructions. Register names are as follows: 


General Register Numbers Names 

0 RO 

1 R1 ,AP 
2 R2 

3 R3 

4 R4 

5 R5 

6 R6 

7 R7 

8 R8 

9 R9 

10 R10 
11 Ril 
12 R12 
13 R13 ,EP 
14 R14 
15 R15 ,SP 

Floating Point Register Numbers Names 

0 FO 

2 F2 

4 F4 

6 F6 


Operand Descriptions 


FP= If NO is specified, symbolic names for the Floating-Point 
Registers are not generated. The default is to YES. 


4-86 


Rename a Disk File 


Syntax 


1. [label] RENAME PLIST= { address } 
{ (register) } 


2. [label] RENAME LIBRARY »LIBRARY={ address } 
{'string' } 
,»VOLUME={ address } ,NEWNAME={ address } 
{'string' } {'string' } 
[ ,RESTRICT={NO }] [,BYPASS={NO }] 
{YES} {YES} 
3 [label] RENAME FILE={ address } ,»LIBRARY={ address } 
{'string' } {'string' } 
»VOLUME={ address } »NEWNAME={ address } 
{'string’ } {'string’ } 


[,NEWLIB ={ address }] [,RESTRICT={NO }] [,BYPASS={NO }] 
{'string' } {YES} {YES} 


Restrictions 


If any of the operands is specified as a character string in 
single quotes, then the issuing program must provide for the 
generation of a literal pool. 


RENAME now examines all of the bits of the Option Byte in the 
input parameter list. Previously, bits 3-7 were not examined. 
Therefore, previously coded invocations of RENAME may fail or 
produce undesirable results if bits 3-7 are set. Bits 5-7 of the 
Option Byte are reserved and must be zeroes. 


RENAME requires a minimum of 2K bytes of stack for buffer space 
to rename a library or a file. RENAME requires a minimum of 9K 
of stack for buffer space to rename both a library name and a 
file name for a given file ("Full RENAME"). 


Function 


To rename a disk file or a library on a volume. A “Full RENAME" 
(renaming both a library name and a file name for a given file) 
may alter the Volume Table of Contents; otherwise, the structure 
of the VIOC is not altered. No file that is to be renamed may be 
open when the RENAME is attempted. Note that a "Full RENAME" is 
equivalent to moving a file from one library to another on the 
same volume. 
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RENAME 


If the PLIST= option is not utilized, then RENAME dynamically 
builds its parameter list on the stack, and it becomes’. the 
invoking program's responsibility to pop 32 bytes (40 for "Full 
RENAME") off the stack beyond the return code word. 


Operand Descriptions 


PLIST= 


LIBRARY 


FILE= 


LIBRARY= 


VOLUME= 


The address of a user-generated parameter list, the 
format of which is described in the RENAME SVC in 
Chapter 6. If PLIST= is specified, no other operand is 
allowed; if it is not specified, the macro generates 
code to dynamically build a parameter list on the stack 
prior to issuance of the RENAME SVC. 


PLIST may be specified as a register in parentheses 
containing the address of the user-generated parameter 
list, or as an expression addressing it. 


Indicates that the library specified in the LIBRARY= 
operand is to be renamed. Use of this operand is 
mutually exclusive with the FILE= operand. Note that 
this operation is equivalent to "moving" all the files 
in that library to a new library on the same volume. 
Libraries may not, however, be merged in this manner: 
the library specified by the NEWNAME= operand can exist 
when the RENAME SVC is issued. 


Specifies the name of the file to be RENAMEd. This 
operand may be specified as a character string in 
single quotes which is the name of the file, or as an 
address expression containing the name of the file to 
be renamed. Use of this operand is mutually exclusive 
With the LIBRARY operand described above. 


Specifies the name of the library to be RENAMEd or the 
name of the library containing the file to be renamed. 
This operand may be specified as a character string in 
single quotes which is the name of the library, or as 
an address expression pointing to an eight-byte field 
containing the library name. This operand is required 
if PLIST= is not specified. 


Specifies the name of the volume containing the file 
and/or library to be RENAMEd. This operand may be 
specified as a character string in single quotes which 
is the name of the volume, or as an address expression 
pointing to an six-byte field containing the volume 
name. This operand is required if PLIST= is not 
specified. 
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NEWNAME= 


RESTRICT= 


BYPASS= 


NEWLIB= 


RENAME 


Specifies the new name of the file or library being 
RENAMEd. This operand may be specified as a character 
string in single quotes which is the name of the 
library or file, or as an address expression pointing 
to an eight-byte field containing the library or file 
name. This operand is required if PLIST= is not 
specified. 


YES specifies that the RENAME SVC is to ignore any 
special access rights which may have been’ granted to 
the invoking program, and thus restrict itself to the 
user's LOGON access rights in determining whether the 
user may RENAME the specified file(s). If NO is 
specified, or the operand is omitted, the RENAME 
operation proceeds, utilizing current file access 
rights. 


If NO is specified, or the operand is omitted, the 
RENAME operation performs an expiration date check. If 
the date is unexpired, the entire RENAME operation is 
not performed. If YES is specified, the expiration 
date check is bypassed. 


The name of the library in which the renamed file is to 
be placed. This operand is used only for the "Full 
RENAME" option, that is, for the renaming of both the 
file name and the library name for a given file. The 
library specified by the NEWLIB= operand can exist when 
the RENAME SVC is issued. If omitted, then the same 
library as specified by the LIBRARY= operand is 
assumed. This operand may be specified as a character 
string in single quotes which is the new file name or 


. library name, or as an address expression pointing to 


Example 


LAB1 


an eight-byte field containing the new file mame or 
library name. Use of this operand is mutually 
exclusive with use of the LIBRARY operand. 


RENAME 


FILE=RENFILE , LIBRARY=RENLIBR , VOLUME=RENVOLUME , X 


+LAB1 


+eeete t+ + 


NEWNAME=RENNEWNAME 
PUSHN 0,8 

MVI 0(15) ,0 

MVI 6(15) ,B'00000000' 


MVC 0(6,15) ,RENVOLUME VOLUME 
PUSHC 0(8) ,RENNEWNAME NEW NAME 
PUSHC 0(8) ,RENFILE FILE 
PUSHC 0(8) ,RENLIBR LIBRARY 


SVC 26 (RENAME) 
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PLIST=(R1) 
0,R1 POINT TO USER-DEFINED PARAMETER LIST 
26 (RENAME) 


LIBRARY , LIBRARY=OLDLIB , VOLUME='*MYVOL ' ,NEWNAME=NEWLIB 


0,8 GET TWO WORDS ON THE STACK 

7 (15) ,0 RESERVED; MUST BE ZERO 

6(15) ,B'01000000' SET OPTION FLAGS 

0(6,15) ,=CL6'MYVOL' CURRENT VOLUME NAME 

0(8) ,NEWLIB NEW FILE/LIBRARY NAME 
0,8 RENAME LIBRARY (FILENAME OMITTED) 
0,8,OLDLIB CURRENT LIBRARY NAME 

0,15 POINT TO PLIST WITH STACK TOP WORD 
26 (RENAME) 
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Remove Timer Interval 

Syntax 
[label] RESETIME 

Function 
Cancels an interval timing request previously established 
by 'SETIME' which has not been the subject of a 'CHECK 
INTERVAL’ or previous ‘RESETIME'. A programming error is 


assumed and the issuing program cancelled if there is no 
such request. 


Operand Description 


There are no operands. 


Example 
LAB1 RESETIME 
+LAB1 PUSHN 0,4 
+ MVI 0(15) ,X'80' RESET 
+ svc 32 (RESETIME) 
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Return 


Syntax 


to Invoker 


[ le ] 
| ,CODE={ (register) }| | ,COND=number | 
[label] RETURN [UNLINK] | {expression}| | | 
[ yf ] 


ctions 


Restri 


(A CALL, LINK or program invocation must have occurred for 
the issuing task.) 


Functi 


on 


The RETURN macroinstruction is used to (conditionally) exit 
from a program to the system when normal termination of the 
run is required. It is also used to exit from a subprogram 
and return to the calling program. The stack top pointer 
(register 15) and control register 1 are restored to their 
values before the CALL or LINK which effected entry to _ the 
program or subprogram. General register 1-14 contents are 
restored to their state before the CALL, LINK or program 
invocation. A return code, if requested, is set in 
register 0. Otherwise, register 0 is set to zero. (Note 
that "RETURN CODE=(0)"' leaves register 0 unchanged.) 


Operand Descriptions 


UNLINK Specifies return to the most recent LINK 
issuer, Command Processor or Procedure 
Interpreter, thus terminating all routines 
invoked by a sequence of CALLs. *COND=' must 
not be specified with this operand. 


CODE= If the CODE= operand is supplied, register 0 is 
loaded with the number specified or from the 
register specified. In this case,’ the 
instruction "LA O,number" or "LR 0O,Rn" is 
generated. 

COND= If supplied, specifies the condition codes 
under which the return is to be made, as for a 
machine instruction. If omitted, ‘COND=15' is 


assumed. Invalid if 'UNLINK' operand specified. 


LAB1 RETURN CODE=ZERO , COND=7 
+LAB1 LA RO , ZERO 
+ RTC 7 
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Rewrite a Record 


Syntax 


[label] REWRITE [TABS, JUFB={ (register) } [,COND=number] 
(SELECTED , ] {expression} 


Function 


Rewrites a disk record or workstation line. The file must 
be open in IO or SHARED mode or placed in temporary IO mode 
by the ‘START I0' function. In IO mode, the last 
successful function addressed to the file must have been a 
READ with HOLD option unless the file is a workstation 
file. In SHARED mode, the program must be HOLDing the 
record to be rewritten (as a result of a preceding READ 
with the HOLD option not overridden by a later READ with 
HOLD. Record or line is taken from the user's record area 
as addressed by field UFBRECAREA of the specified User File 
Block (UFB). 


Additional control information (order area) precedes the 
line to be written in the record area for workstation line 
REWRITEs. Refer to the specific device description for 
details on this area. 


For indexed disk file REWRITEs, the key field in the record 


to be rewritten is validated. REWRITE may not change this 
field. 


An error condition discovered on REWRITE will result in 
nonzero ASCII digit settings of the file status bytes 
(UFBFS1, UFBFS2) and return to the address in UFBEODAD or 
UFBERRAD, with the normal return address in register 0. 
Possible file status codes indicating errors are: 
Return to UFBEODAD: 

23 - Block beyond end of file for block-level I/0 
Return to UFBERRAD: 

30 - Permanent I/O error 

34 - Order check on workstation 

95 - Invalid function or function sequence (includes 


key validation failure for indexed file REWRITE) 


If UFBERRAD is binary zeroes, these conditions cause 
program termination. 
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REWRITE 


Operand Descriptions 


TABS 


SELECTED 


COND= 


Indicates that bytes 4-13 of the user's record 
area contain tab position settings for the 
workstation (in ascending order, terminated by 
the first zero item, binary column numbers 
1-80), and that the purpose of the REWRITE is 
to set these tabs. 


Indicates that only those fields with 
selected-field tags set in their field 
attribute characters are to be written to a 
workstation screen. 


The address of a User File Block (UFB), which 
may be supplied as a register specification in 
parentheses, where the register contains the 
UFB address, or as an expression not’ in 
parentheses, where the word addressed is 
assumed to begin the UFB. 


If specified, the number or absolute expression 
becomes the first operand of the JSCI 
instruction by which the REWRITE function is 
entered. Thus the REWRITE is made 
conditional. COND=15 is the default. Register 
1 is loaded with the UFB address even when the 
condition is not satisfied. 


REWRITE UFB=(R2) 

LR 1,R2 SET REGISTER 1 
MVI 8(1) ,B'00000000 ' MODIFIERS 

JSCI 15,8(,1) REWRITE FUNCTION 
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Scratch a File 


Syntax 
is [label] SCRATCH PLIST= {expression} 
{ (register) } 
2. [label] SCRATCH {LIBRARY } ,LIBRARY={ expression} 
{FILE={expression} } {'literal' } 
{ {"literal' }} 
: » VOLUME={ expression} 


{'literal' } 


[,RESTRICT={ NO}] 
[ {YES}] 


[ ,BYPASS={ NO}] 
[ {YES}] 


Function 


To delete ("scratch") a disk file or a library of disk files on a 
volume, making the space utilized by the file(s) available _ for 
reallocation and removing all references to the file(s) from the 
Volume Table Of Contents (VTOC). No file that is to be deleted 
may be open when the SCRATCH is attempted. 


Return codes in binary in the top word of the stack indicate the 
result of the request: 


Nl 
oO 
t 


Return code File or library successfully 
scratched 

4 ~ Volume not mounted 

8 - Volume used exclusively by other user 
All buffers in use, no scratch 

16 - Library not found 

20 - File not found 


Return code 
Return code 
Return code 
Return code 
Return code 


tow tf ott 
rary 
ho 
' 


Return code = 24 - Update access denied, no scratch 
(single-file scratch only) 
Return code = 28 - Unexpired file, no scratch 


(single-file scratch only) 
32 - File in use, no scratch 
VTOC error! FDX1 and FDX2 don't 
agree 
40 - VIOC error! FDX2 and FDR don't agree 
Invalid argument list address 
48 - I/0 error! VTOC unreliable! 
52 - Open, protected, and/or unexpired 
file bypassed in scratching library 


Return code 
Return code 


| 
w 
a 

i 


Return code 
Return code 
Return code 
Return code 


“iuwk 
> 
> 

j 


If space on the volume is lost during SCRATCH because there is no 
room in the VTOC to record released extents, the high-order three 
bytes of the return code word contain the number of blocks lost. 
Otherwise they are zeroed. 
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SCRATCH 


Note: If the PLIST= option is not utilized, it is the program's 
responsibility to pop 24 bytes off the stack beyond the return 
code word on the stack. 


Operand Descriptions 


PLIST= 


LIBRARY 


FILE= 


LIBRARY= 


VOLUME= 


RESTRICT= 


BYPASS= 


- The address of a SCRATCH parameter list. (Fora 


description of the format of the parameter list, 
please refer to the description of the SCRATCH SVC in 
Chapter 6.) If PLIST= is specified, no other operand 
may be specified. If PLIST= is not specified, the 
macro generates code to dynamically build a parameter 
list on the stack prior to issuance of the SCRATCH 
svc. 


Indicates that all files within the library specified 
are to be deleted. Use of this operand is mutually 
exclusive with the FILE= operand. 


Specifies the address at which the file's name is 
located. May be specified as a character string 


-delimited by single quotes, in which case a _ constant 


is assumed. Use of this operand is mutually 
exclusive with the LIBRARY operand described above. 


Specifies the address at which the library's name is 
located. May be specified as a character string 
delimited by single quotes, in which case .a constant 
is assumed. This operand is required if PLIST= is 
not specified. 


Specifies the address at which the volume's name is 
located. May be specified as a character string 
delimited by single quotes, in which case a _ constant 
is assumed. This operand is required if PLIST= is 
not specified. 


If NO is specified, or the operand is omitted, the 
SCRATCH operation proceeds utilizing current file 
access rights. If YES is specified, the operation is 
restricted, assuming only the file access rights of 
the user and ignoring any special access rights of 
the program. 


If NO is specified, or the operand is omitted, the 
SCRATCH operation performs an expiration date check. 
For any unexpired file(s), the SCRATCH is_ not 
performed. If YES is specified, the expiration date 
check is bypassed. 
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SCRATCH 


LAB1 SCRATCH FILE=SCRFILE , LIBRARY=SCRLIBR , VOLUME=SCRVOLUME 
+LAB1 PUSHN 0,8 


MVI 0(15) ,0 
+ MVI 6(15) ,B'00000000' 
+ MVC 0 (6,15) ,SCRVOLUME VOLUME 
+ PUSHC 0(8) ,SCRFILE FILE 
+ PUSHC 0(8) ,SCRLIBR LIBRARY 
+ svc 27 (SCRATCH) 
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Set Task-Related Defaults 


Syntax 


SET PROGVOL= 


[label] 


- ,INVOL= 


,»OUTVOL= 


»POOLVOL= 


»PRINTER= 


,FILECLASS= 


»PRTCLASS= 


,RUNVOL= 


, JOBQUEUE= 


» JOBLIMIT= 


{ (register) } 
{'string' } 
{address } 


{ (register) } 
{'string' } 
{address } 


{ (register) } 
{'string' } 
{address } 


{ (register) } 
{'string’ } 
{address } 
{ (register) } 


{'string' } 
{address } 


{ (register) } 
{‘string' } 
{address } 


{ (register) } 


{'string' } 
{address } 
{ (register) } 
{‘string' } 


{address } 
{ (register) } 
{'string' } 
{address } 
{ (register) } 
{'string' } 
{address } 
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,PROGLIB= 


» INLIB= 


,OUTLIB= 


»WORKVOL= 


»PRNIMODE= 


,LINES= 


»FORM#= 


»RUNLIB= 


, JOBCLASS= 


{ (register) } 
{'string' } 
{address } 


{ (register) } 
{‘string' } 
{address } 


{ (register) } 
{'string' } 
{ address } 


{ (register) } 
{*string’ } 
{address} 


{ (register) } 
{‘string' } 
{address } 


{ (register) } 
{‘string' } 
{address } 


{ (register) } 
{'string’' } 
{address  } 


{ (register) } 
{'string’' } 
{address } 


{ (register) } 
{'string' } 
{address } 


SET 


Restrictions 


All library and volume name specifications (except literals) must 
reference eight- and six-byte fields respectively, as the SET SVC 
cannot determine the length of the character string and assumes 
the maximum. 


If any operand is specified as a literal or an integer, then the 
user program must allow for the generation of a literal pool. 


Function 


Allows user programs to set default values according to the 
operands specified. These values are used by the various system 
utilities and SVCs. Note that none of the operands have defaults 
and that any unspecified operands will be unaffected. 


Operand Description 
NOTES: 


(1) All operands are optional (although at least one should 
be specified). 


(2) Operands may be specified as: 


(a) A register in parentheses pointing to a 
character string which is the desired value. If 
the item is numeric (PRINTER, LINES, or FORM#), 
then the value is assumed to be in binary. 


(b) A character string in single quotes which is the 
desired value, except for the numeric items 
(PRINTER, FORM#, and LINES) which use an integer 
(not in quotes) which is the desired value in 
decimal, 


(c) An expression addressing a character string 
which is the desired value. If the item is 
numeric (PRINTER, LINES, or FORM#), then the 
value is assumed to be in binary. 


PROGVOL= Default program/procedure volume name. 

PROGLIB= Default program/procedure library name. This 
pair of operands is used only in procedures, for 
programs run by those procedures, and identify 
default library and volume names for all such 
programs. 
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INVOL= 
INLIB= 


OUTVOL= 
OUTLIB= 


SPOOLVOL= 


WORKVOL= 


PRINTER= 


PRNIMODE= 


FILECLASS= 


Default non-output volume name. 

Default non-output library name. This pair of 
operands is used primarily by the OPEN SVC _ to 
locate files OPENed as input. 


Default output volume name. 

Default output library name. This pair of 
operands is used primarily by the OPEN SVC to 
assign files OPENed as output. 


Default volume for assignment of SPOOLed (Print) 
files. 


Default volume for assignment of WORK files. 


Default printer device number for on-line 
printing. Note that this operand in no way 
affects printer assignment for SPOOLed files. 
This number must be in the range 0 to 255. 


Default print mode. Permissible values and 
their meanings are as follows: 


0 ONLINE: Printing will be done using 
the printer as a direct output 
device; a Print file is NOT created. 


) SPOOL: Print files will be created 
and will be queued by the System 
Task (@SYSTSK@) for printing at the 
earliest opportunity, 


K KEEP: Print files will be created 
but will NOT be queued for printing 
by the System Task. 


H HOLD: Print files will be placed in 
the user's Print Library and will be 
queued by the System Task, but will 
NOT be printed until requested by 
the system operator or the user. 


Default file protection class. The following 
values are valid: 


# Accessible only by Security 
Administrators and the 
Owner-of-Record. 


$ READ only files. READ access 


granted to all users regardless of 
the individual access privileges. 
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SET 


LINES= 


PRTCLASS= 


FORM#= 


RUNVOL= 
RUNLIB= 


JOBQUEUE= 


JOBCLASS= 


@ EXECUTE only files. EXECUTE access 
granted to all users as above. 


A-Z Accessible by users with class 
access privileges matching the type 
of access desired. 


(BLANK) Unprotected file. WRITE access 
implied for all users regardless of 
their individual access privileges. 


Default number of lines-per-page. This operand 
is used primarily by the Print functions of 
system utilities. This number must be in the 
range 0 to 255. 


Default print class. This operand determines 
the class to which print requests sent to the 
system task will be assigned. Printer 
assignment, scheduling priority, and header page 
options are set for each class by the system 
operator and, as such, may vary from time to 
time. Valid values are the letters A-~Z, or a 
blank. 


Default form number for Print files. The 
association of a form number with a specified 
form is  installation-defined. Thia number 
becomes part of the queve record for a Print 
file and is examined by the System Task. This 
number must be in the range 0 to 254. 


Default program/procedure execution volume 

and library name. This operand 

pair is used by the Command Processor RUN 
command to locate program/procedures to be 
executed. 


Default job status for a background job. 
Determines when the submitted background job is 
executed. Possible values are: 


R - Run: The job is executed as soon as 
possible. 

H - Hold: The job is held in the job queue 
until it is released for execution 


Default job class for a background job. 
Background jobs are processed according to the 
job class priority hierarchy specified from the 
Operator's Console. Within a given job class, 
background jobs are processed in order of 
submittal. Possible values are A-Z. 
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JOBLIMIT= 


Example 


SET 
PUSH 
PUSHN 


POP 


SET 


Default CPU time limit for job execution. The 
time limit is specified in seconds. Possible 
values are 0-35999 (thus the maximum time limit 
is 99:59:59). If zero, then the job has no time 
limit. 


PROGVOL=(R2) ,PROGLIB='MYLIB' , PRINTER=PRTID , FORM#=(R5) , LINES=55 


0,0 SAVE REGISTER ZERO IN THE STACK 
0,64 PUSH AREA FOR SVC PLIST 

0(64,15) ,0 (15) INITIALIZE AREA TO ZEROES 

SET DEFAULT PROGRAM VOLUME NAME 

R2,0(,15) PLACE ADDRESS IN PLIST 

SET DEFAULT PROGRAM LIBRARY NAME 

RO ,=CL8'MYLIB' POINT TO LITERAL 

RO ,4(,15) SET ADDRESS IN PLIST 

SET DEFAULT PRINTER NUMBER 

RO ,PRTID POINT TO DATA ITEM 

RO ,40(,15) PLACE ADDRESS IN PLIST 

SET DEFAULT LINES-PER-PAGE 

RO ,=AL1 (55) POINT TO LITERAL 

RO,52(,15) PLACE ADDRESS IN PLIST 

SET DEFAULT FORM NUMBER 

R5,60(,15) PLACE ADDRESS IN PLIST 

60(15) ,x‘80' FLAG END OF PLIST 

35 (SET) ISSUE SVC | 

0,0 RESTORE REGISTER ZERO FROM STACK 
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Set Interval Timer 


Syntax 


[label] SETIME {UNTIL}= { (register) } 
{CSEC } {expression} 


Function 


Sets a timer interval for the issuing task to expire at the 
time specified, or after the number of 1/100 second units 


specified. If a previous interval timing request was 
active for this task, it is cancelled and the new one 
instated. 


Operand Descriptions 


UNTIL= Either a register specification in parentheses, 
where the register contains a binary time value 
in 1/100 second units into a day (from 
midnight), or an address expression, where the 
four bytes starting at that address contain the 
time as above. To request expiration at some 
time tomorrow, the value supplied must be 24 
hours plus the required time-of-day. A 
requested time less than the current 
time-of-day will result in immediate expiration. 


CSEC= Either a register specification in parentheses, 
where the register contains the number of 1/100 
second units to delay processing, in binary; or 
an expression, not in parentheses, for the 
required number of 1/100 second units. May not 
exceed one day. 


Example 
LAB1 SETIME CSEC=55 
+LAB1 PUSHA 0,55 
+ MVI 0(15) ,O UNITS 
+ SVC 32 (SETIME) 
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Start File Processing in Specified Mode or at Specified Record 
Location 


Syntax 


[label] START {IO 
{OUTPUT 
{EXTEND 
{BEGIN 


} ,UFB={ (register) } [,COND=number] 

} 

} 

} 
{SKIP } 

} 

} 

} 

} 

} 


{expression} 


{EQ 

{GT 

{GE 

{ ATINT 

{WAIT 

{HOLD } 

{RELEASE} 

{TCWAIT[ ,MULTIPLE ] [TIMEOUT={register }]} 
{ [ (MULTIPLE ,ATTN) J [ {expression}]} 
{HALTIO} 


Function 
The function of START differs for various file types. 
(1) Consecutive disk files (normal DMS): 


START is valid in OUTPUT or EXTEND open modes only. 
"START I0' writes any remaining buffered records to 
disk, and then enters temporary IO mode, with the next 
record to be read set to the first record of the file. 
‘START OUTPUT’ places the file in OUTPUT mode, after 
effectively deleting all records in the file (but not 
necessarily releasing space allocated for them ona 
disk file). The next WRITE will then place a new first 
record in the file. ‘START EXTEND’ places the file in 
EXTEND mode (thus having significant effect only when 
‘START I0' has been previously issued). The next WRITE 
will then add a record to the end of the file. 
Possible error indications in the file status bytes 
(UFBFS1, UFBFS2) are as follows: 


30 - Permanent I/0 error 
95 - Invalid function or function sequence 
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(2) 


(3) 


(4) 


Consecutive disk files: 
(variable-length records, normal DMS): 


START BEGIN and START SKIP are valid in INPUT and I0 
modes. A READ NEXT issued after START BEGIN will read 
the first record of the file. A READ NEXT issued after 
a START SKIP (with a signed binary number "n" in the 
word addressed by UFBKEYAREA) will skip over "n'" 
records and read the record after them (n>0), will 
merely read the next record (n=0), will reread the 
current record (n=~-1) or will read a preceding record 
(n<-1). 


Consecutive disk and magnetic tape files (physical 
access method) : 


START WAIT is valid in INPUT, OUTPUT, or IO modes. The 
program is paused until a preceding READ or WRITE 
operation is completed. START I0 and START OUTPUT have 
the same function as for normal consecutive DMS. 
Possible error indications in the file status bytes 
(UFBFS1, UFBFS2) are as follows: 


30 - Permanent I/O error 

95 - Invalid function or function sequence 
(including START WAIT issued without preceding 
block-level READ, REWRITE OR WRITE) 


Indexed disk files: 


START is valid in INPUT, IO or SHARED modes only. 
Valid options are EQ, GIT and GE. The START function is 
essentially a READ (KEYED, NODATA) operation (key from 
area addressed by UFBKEYAREA, with length UFBKEYSIZE) 
with the following additional options: 


EQ - If a record with the specified key is not 
found in the file, invalid-key and 
no-record-found conditions are indicated. 
(This is like READ KEYED.) 


GT - The first record with key greater than the 
supplied key is sought. (Collating sequence 
is normal ASCII.) If no such record is found, 
invalid-key and boundary-violation conditions 
are indicated. 


GE - The first record with key greater than or 


equal to the supplied key is sought. 
Otherwise like the GT option. 
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After a successful START function, a succeeding READ 
(without KEYED option) will read the record located by 
START. Successive READs will then read _ successive 
records. 


If UFBGKSIZE is not all binary zeroes, the binary value 
in UFBGKSIZE is used as the key length for the above 
searches, in place of UFBKEYSIZE. UFBGKSIZE may be set 
by the user's program before issuing a START. It must 
always be less than or equal to UFBKEYSIZE. If not, a 
fatal error resulting in program termination will 
occur. UFBGKSIZE is set to zero by every such START 
function. 


Possible invalid-key and error indications in the file 
status bytes (UFBFS1, UFBFS2) are as follows: 


23 - Invalid-key, no record found 

24 - Invalid-key, boundary violation 

30 - Permanent I/O error 

95 - Invalid function or function sequence 


(5) Workstation files: 


The only valid option is 'ATINT'. Only the file status 
bytes are modified. They are set as follows: 


UFBFS1 - 0 

UFBFS2 - AID character as indicated on the most 
recent interruption for this workstation; 
hexadecimal values as follows: 


20 - Keyboard unlocked. 

21 - Keyboard locked by # REWRITE 
function or other write to 
workstation. 

3F - Display screen, tab positions, 
or other workstation status 
lost. 

Other - Indication of last AID 
character (e.g., ENTER, PROGRAM 
FUNCTION) received. See 


specific device description. 


(6) Disk files (10 or SHARED open modes only): 


START HOLD acquires temporary exclusive control of the 
entire File addressed. It has no significant effect in 
IO mode. 


START RELEASE may be used to remove a record or File 
from HOLD status without issuing a REWRITE, DELETE, or 
another READ with the HOLD option. It has no 
significant effect in IO mode. 
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7) 


For all START functions and all file types, an 
invalid-key condition results in return to the address 
in UFBEODAD, with the normal return point address in 
register 0. Other exceptional and error conditions 
result in return to the address in UFBERRAD, with the 
normal return point address in register 0. If UFBEODAD 
is zero, UFBERRAD is used in its place. If UFBERRAD is 
zero as well, any exceptional condition results in 
abnormal termination of the program. 


Telecommunication devices: 


START TCWAIT waits for the completion of current ‘READ‘ 
or 'WRITE' operations issued on this TC file (this UFB). 


START TCWAIT, MULTIPLE waits for completions on all TC 
devices for which this program has an outstanding 
"READ' or 'WRITE' operation. 


START ,TCWAIT, (MULTIPLE ,ATTIN) waits for unsolicited 
interrupts for any TC lines, which this program 
controls, in addition to START TCWAIT, MULTIPLE. 


The TIMEOUT operand can be used in conjunction with 
either of the above options. The expression field is 
an unsigned integer with value less than or equal to 
255. If ‘register’ is specified, the right-most byte 
of the register will be used. In either case, TIMEOUT 
specifies the time interval in seconds. 
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The following table summarizes the uses 


Fixed 
Consecutive 
RAM 


Variable 
Length 


Consecutive 
RAM 


Indexed 
RAM 


BAM 


PAM 


START - MODES OF USE WITH DISK 


Open 
for 
Input 


Start SKIP 
BEGIN 


Start EQ 
GT 
GE 


Start WAIT 


Open 

for 

Output 

Start 10 
OUTPUT 
EXTEND 

Start 10 
OUTPUT 
EXTEND 

Start 10 
OUTPUT 
EXTEND 


Start WAIT 


Start 10 
OUTPUT 


of START: 
FILES 
Open Open 
for for 
1/0 EXTEND 
Start I0 
OUTPUT 
EXTEND 
Start SKIP 
BEGIN 
Start I0 
OUTPUT 
EXTEND 
Start EQ 
GT 
GE 
Start I0 
OUTPUT 
EXTEND 


Start WAIT 
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Open 
for 
Shared 
10 


Start EQ 
GT 
GE 
Start HOLD 
RELEASE 


START 


Operand Descriptions 


10 
OUTPUT 
EXTEND 
BEGIN 
SKIP 
EQ 

GT 

GE 
ATTNT 
WAIT 
HOLD 
RELEASE 
TCWAIT 
HALTIO 


UFB= 


COND= 


As described above. 


The address of a User File Block (UFB), which may 
be presented as a register specification in 
parentheses, where the register contains the UFB 
address, or as an expression not in parentheses, 
Where the word at the address designated is 
assumed to begin the UFB. 


If specified, the number or absolute expression 
becomes the first operand of the JSCI instruction 
by which the START function is entered. Thus the 
START is made conditional. COND=15 is the 
default. Register 1 is loaded with the UFB 
address even when the condition is not satisfied. 


START GE ,UFB=(R2) 


LR 1,R2 SET REGISTER 1 
MVI 16(1) ,B'00000011' MODIFIERS 
JSCI 15,16(1) START FUNCTION 
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Submit Job or Print Request 


Syntax 


(1) [label] SUBMIT JOB [,PLIST= { (register) }] [,PROCNAME={ (register) }] 
[ { expression}] [ 


[ ,LIBRARY= {(register) }] [,VOLUME= 


[ 
[ 


[, JOBNAME= { (register) }] 
[ 


C 


[ ,STATUS= 


C 
[ 


{'literal' 


HE 


{ expression}] [ 


{'literal' 


Hl 


{ expression}] [ 


{ "RUN' 
{*HOLD' 


{ expression}] 


,CPULIMIT=({ (register) } [,{' 

{ expression} [,{'PAUSE' 
Lat 
C,{ 


}] f 
}] f 
[ 


WARN' 


CANCEL' 


{*literal' }] 


{(register) }] 


{'literal' 


}] 


{ expression}] 


{‘literal' 


{ ,JOBCLASS={ (register) }] 


}] 


{ expression}] 


»DISP= {"REQUEUE' 


}] 


{ expression}] 


}])] ([,DUMP={'YES' }) 
Kl IC {'NO‘ }] 
Hl1ic {'PROG' }) 


expression} ] ] [ 


{ expression}] 


(2) [label] SUBMIT PRINT[,PLIST={ (register) }] [,FILENAME={ (register) }] 
f { expression}] [ 


Function 


[ 
[ ,LIBRARY= 
[ ,PRTCLASS= 


{ ,COPIES= 


{ 
{ (register) }] 
{‘literal' }] 
{ expression}] 


{ (register) }] 


h] C 


[ ,VOLUME= 
[ 
f 


[ ,FORM#= 


{‘literal' }] [ 


{ expression}] 


{(register) }] 


[ 


{ , STATUS= 


{'literal' }] [ 


{ expression}] 
{'REQUEUE' }] 
{'SAVE' }] 
{ expression}] 


[ 


{"literal' }] 
{ expression}] 


{ (register) }] 
{‘literal' }] 
{ expression}] 


{ (register) }] 
{‘literal' }] 
{ expression}] 


{'SPOOL' }] 
{"HOLD' }] 
{ expression}] 


If initial parameter is JOB, SUBMIT requests the queuing of 
a procedure file for execution as a non-interactive job. 


If initial parameter is PRINT, SUBMIT requests 
of a print file for printing. 


the queuing 


SUBMIT issues a return code 


in the stack top word indicating the success/failure/status 
of the operation. 
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Operand Descriptions 


PLIST= A 44-byte user-supplied parameter list | (FULLWORD 


ALIGNED) 
follows: 


for use by the SUBMIT SVC and constructed as 


For “JOB" Requests: 


Bytes 0-7: 


Bytes 8-15: 


Bytes 16-21: 


Bytes 22-29: 


Byte 30: 


Byte 31: 


Bytes 32-35: 


Byte 36: 


The name of the Procedure (PROCNAME) to be 
run. 


The name of the LIBRARY in which the 
Procedure resides. 


The name of the VOLUME on which the 
Procedure resides. 


A user-supplied JOBNAME or spaces. 


The JOBCLASS to which this job is to be 
queued. 


The action to be taken in case of an 
abnormal termination of this job: 


Xx'CO' =- Produce a DUMP for this job 
('YES'). 

X'80' - Do NOT produce a DUMP for this 
job ('NO'). 

X'00' - Produce a DUMP only if requested 


by the abnormally terminating 
program ('PROG'). 


The CPU Time Limit (in timer units) imposed 
upon this job. If zero, then the job has no 
time limit. 


The initial STATUS of this job when it is 
queued: 


X'80' - HOLD - NOT eligible for scheduling 
until released by the operator or the 
submitter. 


X'00' ~- RUN - eligible for scheduling upon 
submission of the request. 
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Bytes 38-43: 


SUBMIT 


Whether or not to check for a CPU Time 
Limit, the action to be taken in case _ the 
limit is exceeded, and whether or not the 
job should be requeued after execution: 


X'80' - Check for timer limit expiration 
(IF a CPU Time Limit is specified 
then this bit MUST be on). 


X'40' - CANCEL this job if the CPU Time 
Limit is exceeded. 

X'20' - PAUSE this job if the CPU Time 
Limit is exceeded. (If neither 
of these bits is on and a CPU 
Time Limit has been set, then a 
WARNing will be issued). 

X'04' - REQUEUE this job after execution. 


RESERVED (Should be ZEROS). 


For "PRINT" Requests: 


Bytes 0-7: 


Bytes 8-15: 


Bytes 167-21; 


Byte 22: 


Byte 23: 


Bytes 24-25: 


Byte 26: 


The name of the File (FILENAME) to be 
printed. 


The name of the LIBRARY in which the file 
resides. 


The name of the VOLUME on which the file 
resides. 


The Print Class (PRTICLASS) to which this 
file is to be queued. 


The Form Number (FORM#) (in binary) of this 
file to be printed. 


The number of COPIES (in binary) of this 
file to be printed. 


The initial STATUS of this file when it is 
queued: 


X'80' - HOLD - NOT eligible for printing 
until released by the 
operator or the submitter. 


X'00' - SPOOL - eligible for printing upon 
submission of the request. 
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Byte 27: 


Whether or not this file should be 
REQUEUEed, SAVEed, or scratched after 
printing: 

X'40’ - REQUEUE this file after printing. 


X'20' - SAVE this file after printing. 


Bytes 28-43: RESERVED (Should be ZEROS). 


"PLIST" may be specified either as a register in 
parentheses pointing to the user-supplied parameter 
list or aS an expression addressing the 
user~supplied parameter list. 


If "PLIST" is specified, then the remaining 
operands are optional and, if present, are used to 
modify the parameter list IN PLACE. The default 
values of any omitted operands are NOT recognized 
so as not to override the value set in the user's 
parameter list. 


If "PLIST’ is not specified, then the remaining 
operands are used to build a parameter list on the 
stack. The default values of omitted operands are 
used in this case. The user is responsible for 
POPping off the 44 bytes beyond the stack top word 
(SVC Return Code) on return. 


“PROCNAME / FILENAME", “LIBRARY, "VOLUME", 
“JOBCLASS/ PRTICLASS", and "FORM#'' are required by 
their respective functions unless "PLIST" is also 
specified. All other operands are always optional. 


PROCNAME/FILENAME= The name of the Procedure to be run or the 


File to be printed. 


LIBRARY= The name of the library in which the 


Procedure/File reside. 


VOLUME= The name of the volume on which the 


Procedure/File reside. 


JOBNAME= An optional user-supplied name for the job to 


be submitted (limited to 8 characters). 


JOBCLASS/PRTICLASS= The class to which the job/print request is to 


be assigned. Valid values are the letters A-Z. 


The above operands may be specified as a 
register in parentheses pointing to the 
required value, a literal in single quotes 
which is the required value, or an expression 
addressing a field containing the required 
value. . 
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FORM#= 


COPIES= 


CPULIMIT= 


STATUS= 


SUBMIT 


The number of the form on which to print this file. 
This number must be in the range 0-254. 


The number of copies of this file to be printed. This 
number must be in the range 1-32767. The default 
value is 1. 


“FORM#H" and "COPIES" may be specified as a register in 
parentheses containing the value in binary, an integer 
not in quotes which is the value in decimal, or an 
expression addressing a field containing the value in 
binary. 


The total amount of time that this job may use the CPU 
(lst sub-operand) and the action to be taken if that 
limit is exceeded (2nd sub-operand) . 


The actual time may be specified as a register in 
parentheses or an expression addressing a 4-byte field 
containing the limit in timer units. A value of zero 
implies that the job has no limit and any action 
indicated by the 2nd sub-operand will be ignored. The 
default is to zero (no limit). 


The action to be taken upon completion may be 
specified either as one of the following literals in 
single quotes, or as an expression addressing a 
one-byte field containing the appropriate flag value 
(See "PLIST" entry for byte 37 ("JOB") above). The 
default is to "WARN". 


‘CANCEL' - Force abnormal termination of the 
Procedure. 
"PAUSE' - Suspend execution of the Procedure until 


resumed by the operator. 
"WARN' - Issue a WARNing message to the operator. 


NOTE: The time (lst sub-operand) may 
always be specified by itself; the action 
on expiration (2nd sub-operand) may only 
be specified by itself if "PLIST" is also 
specified. 


The initial status of the request when it is placed on 
the queue. It may be specified either as one of the 
following literals in single quotes or as_ an 
expression addressing a one-byte field containing the 
appropriate flag value (see "PLIST" entry for byte 36 
("JOB") or byte 26 ("PRINT") above). The default is 
to "RUN'/‘SPOOL': 


‘RUN' - Eligible for scheduling upon submission 
of the request (“JOB only). 
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"SPOOL' - Eligible for printing upon submission of 
the request ("PRINT" only). 


*HOLD' - NOT eligible for print/execution 
scheduling until released by the operator 
or the submitter. 


DISP= The action to be taken at completion of the request. 
It may be specified as a literal in single quotes or 
as an expression addressing a oone-byte field 
containing the appropriate flag value (see "PLIST" 
entry for byte 37 ("JOB") or byte 27 ("PRINT") 
above). The default is to NOT set these options (do 
NOT requeue or save). 


"REQUEUE' - Place the request back onto the queue for 
re-execution/re-printing (for "PRINT" 
requests, this implies 'SAVE'). 


‘SAVE’ ~ Do not scratch this file after printing 
("PRINT" only). 


DUMP= The action to be taken in the event of an abnormal 
termination. It may be specified as a literal in 
single quotes or as an expression addressing a 
one-byte field containing the appropriate flag value 
(see "PLIST" entry for byte 31 above). The default is 


to 'PROG'. 

‘YES’ - Produce a DUMP for this job. 

"NO' - Do NOT produce a DUMP for this job. 

*PROG' - Produce a DUMP only if requested by the 


program abnormally terminating. 
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Return Codes 


= 0 Successful 

4 Volume Not Mounted 

8 Volume in Exclusive Use 

12 All Buffers in Use, Unable to Perform Verification 

16 Library Not Found 

20 File Not Found 

24 Improper File Type (or Zero Records as Indicated in 
Label 

28 File Access Denied 

32 VIOC Error, FDX1/2 Do not Agree 

36 VTOC Error, FDX2/FDR Do not Agree 

40 Invalid Specification of File/Library/Volume 

44 VTOC Unreliable 

48 System Task not Running, 
NO SPOOLED PRINTING OR NON-INTERACTIVE JOBS 

52 Error in Performing XMIT to System Task 

56 Invalid Options Specified In Parameter List 


Examples 

LAB SUBMIT JOB ,PROCNAME='MYPROC' , LIBRARY=PROCLIB , VOLUME=(R5) , x 
JOBCLASS='A' ,CPULIMIT=((R3) ,"PAUSE') ,DISP='REQUEUE' 

+LAB PUSHN 0,44 GET SPACE ON STACK FOR ‘PLIST’... 

+ XC 0 (44,15) ,0(15) ... AND CLEAR IT TO ZEROES 

+ MVC 0(8,15) ,*+10 SET PROCEDURE NAME 

+ B *+12 BRANCH AROUND LITERAL 

+ DC CL8'MYPROC' PROCEDURE NAME 

+ MVC 8(8,15) ,PROCLIB SET LIBRARY NAME 

+ MVC 16(6,15) ,0(R5) SET VOLUME NAME 

+ MVPC 22(8,15) ,*+2(1),C' ' DEFAULT JOBNAME TO SPACES 

+ MVI 30(15) ,c'A' SET JOB CLASS 

+% (STATUS OPTION DEFAULTED TO ‘RUN') 

+ ST R3,32(,15) SET CPU TIME LIMIT 

+ MVI 37(15) ,X'80' FLAG CPU TIME LIMIT SET 

+ Or 37 (15) ,x'20° SET CPU LIMIT EXPIRE OPTION: 

+* X'40' - CANCEL 

+% X'20' - PAUSE 

+% X'00' - WARN 

+ OI 37 (15) ,x'04' SET JOB DISPOSITION TO 'REQUEUE' 

+e (DUMP OPTION DEFAULTED TO "ON 

+* PROGRAM REQUEST ONLY") 

+ PUSHA 0,0(,15) | POINT TO "PLIST" WITH STACK TOP 

+* WORD 

+ MVI 0(15) ,1 FLAG REQUEST TYPE: 1 = JOB 

+% 2 = PRINT 

+ svc 46 (SUBMIT) ISSUE SVC 
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+% 


SUBMIT JOB ,PLIST=MYPLIST , LIBRARY=PROCLIB , JOBNAME=MYJOB , 


PUSHA 


JOBCLASS=(R5) ,CPULIMIT=(,'CANCEL') ,DUMP=DUMPOPT 


0 ,MYPLIST 
0(15) ,1 


MYPLIST+8(8) ,PROCLIB 
MYPLIST+22 (8) ,MYJOB 
MYPLIST+30 (1) ,0 (R5) 
MYPLIST+37 ,X'40' 


MYPLIST+31 (1) ,DUMPOPT 
46 (SUBMIT) 


POINT TO PLIST’ WITH STACK TOP 

WORD 

FLAG REQUEST TYPE: 1 -— JOB 

2 ~- PRINT 

SET LIBRARY NAME 

SET JOB NAME 

SET JOB CLASS 

SET CPU LIMIT EXPIRE OPTION: 
X'40" - CANCEL 
X'20' - PAUSE 
X'00' - WARN 

SET DUMP OPTION 

ISSUE SVC 


PRINT , FILENAME='"MYFILE" , LIBRARY=PRINTLIB ,VOLUME=(R5), X 
PRTCLASS=(R2) ,FORM#=27 ,DISP='SAVE' 


0,44 
0(44,15) ,0 (15) 
0(8,15) ,*+10 
*+12 

CL8'MYFILE' 
8(8,15) ,PRINTLIB 
16(6,15) ,0 (R5) 
22 (1,15) ,0 (R2) 
23 (15) ,27 

25 (15) ,1 


27 (15) ,X'20' 
0,0(,15) 
O(15) ,2 


46 (SUBMIT) 
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GET SPACE ON STACK FOR "PLIST"... 
.«. AND CLEAR IT TO ZEROES 
SET FILE NAME 
BRANCH AROUND LITERAL 
FILE NAME 
SET LIBRARY NAME 
SET VOLUME NAME 
SET PRINT CLASS 
SET FORM NUMBER 
DEFAULT NUMBER OF COPIES TO 1 
(HIGH ORDER BYTE ALREADY CLEARED) 
(STATUS OPTION DEFAULTED TO 
"SPOOL') 
SET DISPOSITION: X‘'40‘' - REQUEUE 

X'20' - SAVE 
POINT TO "PLIST" WITH STACK TOP 
WORD 
FLAG REQUEST TYPE: 1 ~ JOB 

2 - PRINT 

ISSUE SVC 


Set Telecommunications Stream Options 


Syntax 
{label] TCOPTION UFB={ (register) }[,STREAM={READER }] 
{expression} [ {PUNCH }] 
[ {PRINTER}] 
[,DEVTYPE={2780 }] 
[ {3780 }] 
[ {TCDIAG}] 
[ ,COMP={YES}][,PRINT={NO }] [,BLOCKED={YES}] 
[ {NO }I[ {YES}][ {No }] 
[ ,RECSIZE=integer] 
[ ,TRANSMISSION=({TRANSPARENT, J] J 
[ [NONTRANSPARENT , ] J 
[ [BLOCKED, ] J 
[ [UNBLOCKED , ] J 
[ ([UNPADDED ,] ] 
[ [PADDED, ] J 
[ (COMPRESSED, ] ] 
[ [UNCOMPRESSED , ] ] 
[ {EBCDIC] J 
[ [ASCII ]) ] 
Restriction 
None. 
Function 


Sets the TC stream options in the UFB. The TC stream 


options consist of 3 bytes, the data option, 


transmit/receive option, and maximum record size. They are 


stored in the UFBTCDATAOPT , UFBTCXMITOPT, 


UFBICMAXRECSZ. The stream options are defined as follows: 


TC data option: 
bit 0 print format VS records in use 

compressed VS record format 

blocked VS record format 

(reserved) 

for card reader stream 

for card punch stream 

for printer stream 

(reserved) 


OWN 
Nu 
Hon iw 
bt pt et 


oun tt 
WN FH © 
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TC transmit/receive option: 


bit 0 


aa) 


= 1 perform code translation from 
EBCDIC to ASCII 

= 1 compress transmitted record data 

= 1 pad transmitted records to exact 
length with space codes 

= 1 blocked transmitted records 

= 1 transmit in transparent mode 
(reserved) 


The third byte in the TC stream option is equal to the 
maximum or exact transmitted record length minus one. 


Operand Descriptions 


UFB 


STREAM 


DEVTYPE 


PRINT 


BLOCKED 


COMP 


TRANSMISSION 


RECSIZE 


The address of a User File Block (UFB), which 
may be supplied as a register specified in 
parentheses, where the register contains the 
UFB address, or as an expression not in 
parentheses, where the word addressed is 
assumed to begin the UFB. 


To identify the stream of the TC line, valid 
values are READER for cardreader, PUNCH for 


‘cardpuncher, or PRINTER for printer. 


To identify the device type of the TC line, 
valid values are 2780, 3780 for IBM-2780, 
IBM-3780 batch TC stream, and TCDIAG for TC 
diagnostic use. This option does not take 
effect until the addressed UFB has been OPENed 
again (unlike the other options of TCOPTION, 
Which are effective on the next DMS Function 
request) . 


If YES, the corresponding bit in the data 
option will be set to 1; otherwise, to 0. 


If NO, the corresponding bit in the data 
option will be set to 03 otherwise, to 1. 


If NO, the corresponding bit in the data 
option will be set to 0; otherwise, to l. 


The bits in the transmit/receive option will 


be set according to the operand specified. 
For example, if TRANSPARENT is specified, the 
corresponding bit 4 in the transmit/received 
option will be set to 13 if NONTRANSPARENT is 
specified, the bit 4 in the transmit/received 
option will be set to 0. 


The 3rd byte in the TC stream option will be 
set to the integer value minus 1. 
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Example 
LAB1 TCOPTION UFB=(R2) ,STREAM=PUNCH ,BLOCKED=NO ,RECSIZE=10, x 
TRANSMI SSION= (NONTRANSPARENT , PADDED) 
’ +LAB1 LR 1,R2 SET REGISTER 1 
+ MVI 85 (1) ,65 SET TC DATA OPTIONS 
+ MVI 86(1) ,B'01111000' SET TC XMIT OPTIONS 
+ MVI 87 (1) ,10-1 SET TC MAXIMUM RECORD SIZE 
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Syntax 


[label] TIME 


Function 


The current date is returned in the higher-addressed word 
(stack pointer plus four) of a two-word area pushed onto 
the stack, in one of the following forms: 


JUL - as a packed number OOYYDDDF, where YY is the 
year, DDD the day in year, and F a hexadecimal 
'F' (positive sign) 3 


YMD - as a packed number OYYMMDDF, where YY is’ the 
year, MM the month, DD the day, and F a 
hexadecimal 'F'. 


If HMS is specified (or by default), the current time is 
returned in the lower-addressed word of the two-word area 
pushed onto the stack, in packed digits: HHMMSSth, where 


HH is hours in day, 

MM is minutes in hour, 

SS is seconds in minute, 

t is tenths of second in second, 
h is hundredths in tenth. 


' The minimum time value is 00000000. The maximum is 
23595999. 


If CLK is specified, the current clock value is returned in 
the lower-addressed word of the two-word area pushed onto 
the stack, in binary, in 1/100 second units from the 
previous midnight. 


Operand Descriptions 


See the above function description. Omitted operands 
default to 'JUL' and ‘HMS’. 


Example 
LABL TIME JUL | 
+LAB1 PUSHA 0,0 'JUL' REQUEST 
+ PUSHA 0,0 ‘'HMS' REQUEST 
+ SVC 2 (TIME) 
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Syntax 


[label] UFBGEN [PRNAME=p1] 


[,MODE={OUT  }] [,FORG={CONSEC }] 


{IN } { INDEXED} 
{10 } {ANY } 
{EXTEND} 
{ SHARED} 
[ ,;COMP={YES}] { ,PRINT={YES}] 
{NO } {NO } 
{ ,NRECS=p2 ] [ ,RECSIZE={integer}] 
{0 } 
{ANY } 
[ ,BUFSIZE={integer}] [ ,FORM={0 }] 
{2048 } {1-255} 
[ ,DEVNO=integer] [,KPOS=p4 ] 


[,DPACK={100 }] 
{1-100} 


[,IPACK={100 }] 
{1-109} 


[ ,VERIFY={YES}] 
{NO } 


{ ,RELEASE={YES}] 
{NO } 


[,LIBRARY=p7 ] [ ,VOLSER=p8 ] 


[ NODISPLAY={ YES}] [ ,RECAREA=p9 ] 


{NO } 
[ ,ERRAD=p11 ] [ ,EODAD=p12 ] 
[,ALTCNT={0 } ,ALTAREA=p15] 
{1-16} 


[ ,BLKAL={YES} ,NBLKS=p13] 
{NO } 
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[ ,DEVCLASS={DISK }] 


{PRT } 
{wS  } 
{MTAPE} 


[ ,VLEN={ YES} 
{NO } 


[ ,PROG={YES}] 
{NO } 


[ ,BLKSIZE={integer}] 
{0 } 

[,PRTCLASS={A_ }] 
{B-Z} 

[,KSIZE=p5 ] 


{ ,NOVTOC={YES}] 
{NO } 


[,FILENAME=p6 ] 
[ ,FILECLAS={0 }] 
{# ,A-Z} 
[ ,KKEYAREA=p10 ] 
[ ,POOL={YES} ,BCT=p14] 
{NO } 


[,{PAM}={YES}] 
{BAM} {NO } 


[,STREAM={READER }] 
{PUNCH } 
{PRINTER} 


UFBGEN 


[ ,TRANSMISSION=[{TRANSPARENT }] [,{BLOCKED }] 


{ NONTRANSPARENT } {UNBLOCKED} 
[,{UNPADDED}] [,{COMPRESSED }] [,{EBCDIC}]] 
{PADDED } { UNCOMPRESSED} {ASCII } 
[ MCTYPE={2780 }] [ ,EOD=EOV] 
{3780 } . 
{TCDIAG} [,LABEL= { [NL] [,AL](,IL] [,ANY]}] 

[ ,DEN={556 }] [ ,FSEQ={integer}] [ ,VSEQ={integer}] 
{800 } tL } {1 } 
{1600} 

[ ,ALLOWPAPE={YES}] [ ,TRACK7={ YES} ] [ ,HEADER={PARTIAL}] 

{NO } {NO } {FULL  } 

[ ,AALLOWNL={YES}] [ ,PARITY={EVEN}] [ ,PLOG={YES}] 

{NO } {ODD } {NO } 


Function 


Generates a User File Block (UFB) with the specified fields 
initialized. This macroinstruction does not produce 
executable code. 


Operand Usage 


The following operands are only used for Physical or Block Access 
Method: 


PAM=YES 
BAM=YES 

BLKAL=YES 
NBLKS=p13 


The other operands are for the normally used Record Access 
Method. The following table summarizes their use. 
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Operand Usage Table (Record Access Method) 


Legend: 

R = Required for Open processing. Can optionally be set 
1 by the program prior to OPEN. 

0 = Optional for Open processing. Can also be set by 
1 the program before OPEN. 

R = Required for DMS functions. Can be set by the pro- 
2 gram before use. 

0 = Optional for DMS functions. Can be set by the pro- 
2 gram before use. 


Underlines are used to identify default values. 
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OPERAND USAGE TABLE (RECORD ACCESS METHOD) 


Commonly used operands 


PRNAME 


DEVCLASS 


MODE 


FORG 


VLEN 


COomMP 


PRINT 


PROG 


2 


NRECS 


RECSIZE 


BUFSIZE 


New 
Consecutive 
Disk Files 

value 
R 1-8 char 
1 alphanumeric 
R OISK 
1 
R OUT 
} 

R CONSEC 
1 
0 YES 
1 
Oo YES 
1 
Oo YES 
7 
Oo YES 
1 
R numeric 
1 
R numeric 
} 
nX2k 


New 
Indexed 
Disk Files 

value 
R 1-8 char 
1 alphanumeric 
R DISK 
1 
R OUT 
7 
R INDEXED 
1 
0 YES 
1 
Qo YES 
1 
R numeric 
1 
R numeric 
] 7 
0 n*2k 


Existing 


Disk 
Files 


— 


value 


1-8 char 
alphanumeric 


DISK 


{IN,I0, } 
{EXTEND, } 
{SHARED } 


{CONSEC, } 
{ INDEXED, } 
{ANY } 


YES 


YES 


YES 


{ANY , numeric} 


n¥2k 


New 


Work or Temp 


—_ 


~ 


R 


Files 
value 


1-8 char 
alphanumeric 


numeric 


numeric 


nX2k 


R 


_ 


— 


—_ 


New 
Print 
Files 
value 


1-8 char 
alphanumeric 


PRT 


out 


ONSE 


E 


< 
rm 
in 


(1 »000 snumeric) 


{134,numeric} 


nX2k 


Workstation 
Files 
values 

R 1-8 char 


~_ 


R 


alphanumeric 


WS 


ONSE 


{1924, numeric} 


(GOHLAN SSHOOV THOONY) AIAVL ADVSN ANvuAdO 


LOl-¥ 


Operands used for print files only 


FORM 


PRTCLASS 


DEVNO 


New 


Consecutive 
Disk Files 


value 


New Existing 
Indexed Disk 
Disk Files Files 

value value 


Operands used for new indexed files only 


KPOS 
KPOS 


KSIZE 


OPACK 


TPACK 


Special 


3 
NOVTOC 


4 
VERIFY 


purpose operands 


0 YES 


R 
R 


numeric 
numeric 


numeric 


numeric 


1-100 


numeric 
1-100 


0 YES 


YES 


New 
Work or Temp 
Files 


value 


Oo YES 


New 
Print 
Files 


value 


{0,1-255} 


{A,B-2Z} 


numeric 


YES 


Workstation 
Files 


value 


Operands used to default run-time assignments 


8cl-v 


New New Existing New New Workstation 
Consecutive Indexed Disk Work or Temp Print Files 
Disk Files Disk Files Files Files Files 
value value value value value value 
5 0 1-8 char 1-8 char 0 1-8 char R #AAAA 
FILENAME 1 alphanumeric alphanumeric 1 alphanumeric 1 or 
#HAAAA 
(See Note 5) where AAAA 
is 1-4 char 
alphanumeric 
See NOTE (1) 
§ Q 1-8 char 1-8 char 0 1-8 char 
LIBRARY 1 alphanumeric alphanumeric 1 alphanumeric 
5 Q 1-6 char 1-6 char 0 1-6 char 
VOLSER 1 alphanumeric alphanumeric 1 alphanumeric 
§ 0 {#A-Z} {#,A-Z} R {#,A-Z} R {#,A-2} 
FILECLAS 1 } 1 
6 0 YES YES GO YES R YES R YES R YES 
NODISPLAY 1 1 1 1 1 
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Operands used for OMS requests 


RECAREA 


KEYAREA 


ERRAD 


EODAD 


New 
Consecutive 
Disk Files 


value 


R address in 
2 segment 2 


0 instruction 
2 address 


0 instruction 
2 address 


New 
Indexed 
Disk Files 


value 


R address 


in 


2 segment 2 


R address 


in 


2 segment 2 


0 ainstruction 


2 address 


0 instruction 


2 address 


Existing 

Disk 

Files 

value 

0 address in 
2 segment 2 

Q address in 
2 segment 2 

0 instruction 
2 address 

Q instruction 
2 address 


New 


Work or Temp 


Na 


°o 


oO 


Files 


value 


address in 
segment 2 


instruction 
address 


instruction 
address 


New 
Print 
Files 


value 


address in 
segment 2 


instruction 
address 


instruction 
address 


Workstation 


na 


Files 


value 


address in 
segment 2 


instruction 
address 


instruction 
address 


UFBGEN 


Notes: 


(1) 


(2) 


(3) 


(4) 


(5) 


(6) 


(7) 


The escape characters # and ## are used to request 
unique name generation and to identify work files () 
and temporary files (HH to the system. Work Files and 
temporary files are placed in the user's workfile 
library regardless of what is supplied for library and 
volume. The work files are automatically scratched 
when the file is closed. The temporary files are 
automatically scratched at the end of the run. 


NRECS should preferably be set by the program as a 
value determined after opening the associated input 
file(s) and learning its (their) size. 


See the description of NOVTOC files. When NOVTOC is 
used, FORG=CONSEC, VLEN=NO, COMP=NO, and FILENAME, 
LIBRARY, and FILZCLAS are ignored. 


The use of the VERIFY option significantly degrades 
performance. Its use, unless specifically intended, is 
not recommended. 


These operands represent run-time parameters ultimately 
determined via GETPARM. Unless required to identify 
WORK or TEMP files, these operands serve only to 
provide default values. If left unspecified, defaults 
are provided by OPEN using values supplied via the SET 
command or via system conventions. 


Causes a GETPARM type "ID" to be issued, thus 
suppressing user interaction. Should be used to 
minimize transactions for fixed file specifications 
only. 


Other file organizations including INDEXED, VLEN, COMP, 
PRINT, and PROG, are supported but apparently not very 
useful. If these organizations are used, other 
supplied operands must be consistent. 


Notes on operands 


PRNAME= 


FORG= 


The parameter reference name is the fundamental 
identifier used to locate or solicit run-time parameter 
information. The prnames used should be indicative of 
function. 


The file organization parameter is used for existing 


files to verify file organization. If FORG=ANY is 
specified, any file organization is accepted. 
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VLEN= 
PRINT= 
PROG= 
NRECS= 


RECSIZE= 
BLKSIZE= 


BUFSIZE= 


DEVNO= 


TPACK= 
DPACK= 


NOVTOC= 


RELEASE= 


RECAREA= 
KEYAREA= 


DEVCLASS= 


VERIFY= 


BLKAL= 


UFBGEN 


FORG=ANY can be specified for tape in INPUT mode. 
unlabelled tape, FORG is set to consecutive. 


For 


These attributes are used for existing files to 
limit acceptance to files of the indicated 
attribute. 


The number of records is defaulted to 1000 for existing 
files. 


The record size (or maximum record size) and block 
size are used for existing files to verify this file 
attribute. A RECSIZE (BLKSIZE) of zero is used to 
accept any record (block) size. 


The buffer size option is used to increase efficiency 
for sequential processing. See Chapter 7, DMS, for 
details. 


The device number option can be used for print files to 
request printing on a specific printer. 


These options are used to specify the relative 
percentage of data to space (packing) desired on a new 
indexed file. If not specified, system default values 
are used. 


Optional request for Physical Access Method support or 
multiple-line printing. Defaults to PAM=NO. 


it had 
irrespective of the record 


Optional request to process a disk file as if 
2048-byte logical records, 


size recorded in its file descriptor record. Defaults 
to BAM=NO. 
Optional file attribute for diskette only. Specify 


only for unstructured diskette. 


If set to YES in output mode, the unused disk space 
allocated for the file will be released at file close. 


These operands must be acceptable in "DC A(pn) 


assembler statements. They may be written only when 
the UFB is generated in a sepment 2 'static’ area. 


Valid options are DISK, MIAPE, WS, TC, or PRT. 
Requests read-after-write verification on a disk file. 
Allocate space for a new disk file in number of blocks, 


as specified in UFBNBLKS (see NBLKS=operand), rather 
than in number of logical data records. 
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POOL= Buffer pooling requested. The BCT operand addresses a 
Buffer Control Table in the user-modifiable segment, as 
created by the BCTGEN macroinstruction. 


ALTCNT= An integer between 0 and 16. If not O, ALTAREA operand 
must be supplied. This is the number of alternate 
indices processable for the file. 


ALTAREA= Address of AXD1 block, as generated by the AXDGEN 
macroinstruction. 


STREAM= Sets the TC STREAM DATA option in UFBTCDATAOPT. 


TRANSMISSION= Sets the TC STREAM TRANSMIT/RECEIVE options in 
UFBTCXMITOPT (see also TSOPTION macro). 


MCTYPE= Sets the microcode type for programmable devices. 
Currently, valid options are 2780 and 3780 for IBM-2780 
and IBM-3780 batch telecommunications emulation, and 
TCDIAG for telecommunications diagnostic use. 


EOD= Forces EOD exit when a data management operation 
reaches the end of a tape volume in INPUT mode and an 
EOV1 trailer label is detected. 


LABEL= Magnetic tape label types allowed (NL for no-label, AL 
for ANSI-label, IL for IBM-Label; none, one, or more 
than one may be specified). 


DEN= Magnetic tape density: 556 for 556 BPI tape, 800 for 
800 BPI tape, and 1600 for 1600 BPI tape. The default 
value is 1600 BPI. 


FSEQ= Tape file sequence number. 

VSEQ= Tape volume sequence number for multiple-volume tape 
file. 

ALLOWTAPE= If set to YES, OPEN will allow tape as an 


alternative device for disk file. 


TRACK7= If YES is specified, then 7-track tape is indicated. 
The default is NO. The user must specify a non-zero 
value for tape density in the UFB in the case of a 
7-track tape. 


HEADER= This operand supports IBM DOS labelled tapes. If FULL 
is specified, then both HDR1 and HDR2 file labels are 
present on the tape. If PARTIAL is specified, then 
only HDR1 is present. If HEADER=FULL is specified, and 
no HDR2 is found on the tape, OPEN will cancel with an 
indication of an invalid label type. If HEADER=PARTIAL 
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is specified, but a HDR2 label is found on the tape, 
OPEN will proceed to open the file using structural 
information from the HDR2. 


When only HDR1 is present, the user must provide valid 
information about file organization, record length, and 
block size in the UFB. 


ALLOWNL= Allows non-labelied tape. The default is NO. 


PARITY= If EVEN is specified, then the tape uses even parity. 
If ODD is specified, then the tape uses odd parity. 
EVEN is the default. 


NODISPLAY= If YES is specified, then the OPEN SVC will not 
issue a GETPARM to the user's workstation for 
CANCEL messages or for respecification messages. 


PLOG= If YES is specified, indicates that a file prologue 
will be present. Valid only for Word Processing 
files. This operand is applicable only when OPEN mode 
is OUTPUT, and will be ignored for any other OPEN 
mode. The default is to NO. 
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Write a Record 


Syntax 


[label] WRITE [EOM,] UFB={(register)} [,COND=number] 
(EOT ,] {expression} 


Function 


Writes the next sequential record to a consecutive or 
indexed disk, magnetic tape, or printer file. The file 
must be open in OUTPUT or EXTEND mode, or the specified 
record (Key addressed by UFBKEYAREA) to an indexed disk 
file open in I0 or SHARED mode. For indexed disk files, 
open in OUTPUT or EXTEND mode, the key in the record to be 
written is checked to insure that it is greater than any 
key already in the file. If not, a record sequence error 
is indicated. 


A possible invalid-key condition which can be indicated in 
file status bytes (UFBFS1, UFBFS2) is: 


21 = Record sequence error (indexed files only) 
22 - Duplicate Key (indexed files only) | 
24 - Boundary violation (primary extent = size 


exceeded in output mode ~- indexed files only) 


Possible error conditions which can be indicated in file 
status bytes are: 


30 - Permanent I/O error 

34 - Boundary violation (consecutive files in output 
or extend mode; indexed files in I/O or shared 
mode) 

95 - Invalid function or function sequence 

96 - Invalid data area location or alignment 

97 = Invalid length for device 


An invalid-key condition results in return to the address 
in UFBEODAD, with the normal return address in register 0. 
Other exceptional and error conditions result in return to 
the address in UFBERRAD, with the normal return point 
address in register 0. If UFBEODAD is zero, UFBERRAD is 
used in its place. If UFBERRAD is zero as well, any 
exceptional condition results in abnormal termination of 
the program. 
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Operand Descriptions 


EOM= 


EOT= 


UFB= 


COND= 


This option indicates that the data transmitted by 
the WRITE function is to be followed with a 
telecommunications end-of-message character. 
(Pertains only to batch telecommunications devices.) 


This option indicates that a telecommunications 
end-of-transmission signal is to be transmitted, 
following any data. specified. (Pertains only to 
batch telecommunications devices.) 


The address of a User File Block (UFB), which may 
be presented as a register specification in 
parentheses, where the register contains the UFB 
address, or as an expression not in parentheses, 
where the word at the address designated by the 
expression is assumed to begin the UFB. 


If specified, the number or absolute expression 
becomes the first operand of the JSCI instruction 
by which the WRITE function is entered. Thus the 
WRITE is made conditional. The default is 
COND=15. Register 1 is loaded with the UFB address 
even when the condition is not satisfied. 
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Execute Physical 1/0 


Syntax 


[label] xz10 [ OFB= {address }] [,COMMAND= {address  }] 
[ { (register) }] [ { (register) }] 


[  ,MEMA= {address }] {[ ,BLKNUM= {address }] 
[ { (register) }] [ { (register) }] 


[,BLKSIZE= {address }] { ,PLIST= {address }] 
[ 


{(register)}] [ { (register) }] 

[ ,RELEASE] 
{ ,VOLIO= {YES} ,VCB= {address }] 
[ {NO } { (register) }] 
[,MLPRINT= {YES} »FORM= {LIST}] 
[ {NO } {EXEC}] 
{,UCPRINT= {YES}] [,DEVSTATUS= {CLEAR }] 
{no }] [ {CHECK }] 

f {NOCHECK}] 


Restrictions 


XIO is intended for use by Data Management System routines. XIO 
with the VOLIO option is allowed only when requested from within 
System Mutual Exclusion (SME) state or when addressed to a disk 
volume placed in initialization state by the issuing task. It is 
valid only for disk operations. 


Function 
Normal (without VOLIO option); 


Validates disk extents; acquires available physical pages of 
memory for input operations if the virtual pages referenced 
are not in main memory; "short-term fixes" the virtual data 
page or pages in physical pages during the 1/0 operation; 
constructs indirect data address lists for workstation and 
disk operations; insures that the "change" bit in the Page 
Frame Table for each modified page is set when read-type I/0 
is accomplished; enters the System Start I/O Routine to 
initiate the operation; returns to the issuer on completion of 
its functions with a one-word return code field replacing the 
input parameters on the top of the stack, as described below. 
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With VOLIO option: 


Validates Volume Control Block address, disk block numbers, 
and data address; validates that usage of the VOLIO option is 
to be allowed; translates memory address; converts block on 
volume to disk address; constructs IOCW (from COMMAND operand, 
converted MEMA operand, converted BLKNUM operand) in the IORE 
contained in this VCB; "fixes" data page if required, as 
described above; sets "change" bit if required; enters System 
Start I/O Routine to initiate the operation; returns to issuer 
with return code field on the top of the stack. 


Low-order halfword of return code field - binary return codes: 


0 - Success 

4 -~ Truncation at end-of-extent (non-VOLIO disk 
only) 

8 - Truncation at end-of-cylinder or 


end-of-track (disk only) 

12 - Starting block number beyond end-of-file 
(non-VOLIO disk) or beyond end-of-volume 
(VOLIO disk) 

16 - Invalid data address or data length (Data 
address for disk must be page-aligned; for 
other devices word-aligned. Virtual memory 
area encompassed by data address through 
data address plus block size minus one must 
either be in the segment 2 1/0 buffer area 
or entirely above the XIO parameter list on 
the stack if the XIO is issued from 
unprivileged state) 

20 - Second XIO on file without intervening CHECK 

24 - TC XIO attempted on an OFB that was not 
created as the result of an ‘IPOPEN' on an 
IPCB 

28 -~ TC xXIO attempted on a device reserved 
exclusively by another task 

32 - XI0 has been issued to an inoperative 
workstation and the I/O has not been issued 
(Bit 5 of option flag must be set for 
issuance of this return code) 

36 ~ TC XIO attempted on a peripheral processor 
(DLP) reserved exclusively by another task 

40 - Write XIO attempted to file opened in 
“WPSHARE" mode, file not locked. 

44 -Read xXIO attempted to file opened in 
“WPSHARE" mode, file locked by another user. 


High-order halfword of return code field - residual block 
counts: 


Return codes 4, 8 - block size specified minus 
number of bytes actually read or written. All 
other return codes are always zero. 
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Note: 


If return codes 0, 4, or 8 are set, the I/0 operation 
is queued for initiation and a CHECK must be issued to 
test for completion. If return codes 12, 16, or 20 
are set, the operation has been suppressed. XIO never 
waits for I/0 completion. 


Operand Descriptions 


OFB= 


COMMAND= 


MEMA= 


BLKNUM= 


BLKSIZE= 


PLIST= 


RELEASE 


The address of the Open File Block (OFB) for file 
involved in the I/0 operation. The OFB is supplied 
when the file is OPENed. This operand is not used in 
conjunction with the VOLIO option. 


The address of the value to be placed in the Command 
Byte of the I/O Command Word (IOCW) constructed by the 
XIO SVC. The command byte specifies the operation to 
be performed. Possible values are contained in 
descriptions of the 10CWs for the various commands. 


The address of a 4-byte area containing a virtual data 
address for the I/O operation in its low-order’ three 
bytes, to be translated to a physical address and then 
placed in the IOCW, or as a register specification in 
parentheses where the register contains the virtual 
address. 


For disk I/0, the address of a_ three-byte area 
containing the block number (from zero) within the 
file of the block to be read from the file. If the 
‘VOLIO' option is specified, or if an unstructured 
diskette devcie is being referenced, this is to be the 
block on volume, from block 0. 


For all read or write operations, the address of a 
halfword area containing the length in bytes for the 
operation (or maximum length, as for magnetic tape) 


The address of a 16-byte area containing the parameter 
list for XI0. If this operand is supplied, any other 
operands are used to modify the parameter list after 
it has been moved to the stack. The original copy is 
not modified. 


Specified on a disk or tape write operation when it is 
desired to make the fixed page frames available after 
the operation without preserving their contents (i.e., 
without pageout). 
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VOLIO= 


VCB= 


MLPRINT= 


FORM= 


UCPRINT= 


DEVSTATUS= 


XIO 


If YES is specified, then perform volume-oriented disk 
I/O without extent limitations, as described above. 
Valid only for disk files, and only when requested by 
system routines in System Mutual Exclusion (SME) state 
or when the accessed volume is mounted _ for 
initialization by the issuing task. 


Address of Volume Control Block for a disk volume. 
Required with VOLIO option unless PLIST= is supplied 
or the FORM=EXEC option is specified. Allowed only 
with VOLIO option. Register 1 will be modified if 
this operand is written as an expression not in 
parentheses. 


If YES is specified, then requests a block-print 
opeation of one or more lines. Record-length bytes 
must be provided in the data area if this option is 
not specified. Ignored if the operation is not 
directed to a printer. Data must be 2K-aligned and is 
not moved to the device's resident print buffer. 


If EXEC is specified, the parameter list is assumed to 
already be enstacked. The supervisor call is 
generated. If other operands are supplied, they are 
used to modify the existing parameter list. The 


VOLIO=YES and RELEASE operands must be 
specified if required, even if the parameter 
list already contained these options. 


If LIST is specified, the parameter list is 
created on the stack, but the supervisor call 
is not generated. The RELEASE operand is 
normally not useful on an XIO macroinstruction 
with FORM=LIST. 


If YES is specified, then upper case printing is 
used. The default is NO. 


This operand is intended for the use of hardware 
diagnostics personnel when simulating error conditions 
on serial workstations and printers. 


If CLEAR is specified, XIO will reset two 
fields in the Unit Control Block (UCB), i.e., 
UCBSTATNOTOP and UCBSTATNOCODE, thus permitting 
I/O to a device which is being simulated to 
malfunction. 


If CHECK is specified and an XIO is issued to 


an inoperative workstation, then'a return code 
of 32 is generated and the I/O is not issued. 
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If NOCHECK is specified, then any attempts at 
1/0 to a malfunctioning workstation will cause 
the task to wait for the device to become 
operational. NOCHECK is the default value. 


Examples 


(1) 


(2) 


(3) 


LAB1 XIO  COMMAND=RDCMD , PLIST=XIOPARM 
+LAB1 PUSHC 0(16,0) ,XIOPARM 

+ MVC 51, SP) ,RDCMD 

+ svc 3. (XI0) 


LAB2 XI0O OFB=R (1) ,MEMA=(R2) , BLKNUM=UFBBUFBLOCK , X 
BLKSIZE=UFBBLKSIZE ,COMMAND=WRCMD , RELEASE 
+LAB2 PUSHN 0,16 


+ MVC 8(2,15) ,UFBBLKSIZE 

+ MVC 12(3,15) ,UFBBUFBLOCK 

+ ST R2,4(,15) MEMA 

+ ST R1,0(,15) OFB 

+ MVC 4(1,15) ,WRCDM COMMAND 
+ MVI 0(15) ,x'80° RELEASE 
+ svc 3 (XI0) 


LAB3 XIO  COMMAND=RDCMD ,PLIST=XIOPARM , VOLIO=YES 
+LAB3 PUSHC 0(16,0) ,XIOPARM 


+ MVC 5(1,SP) ,RDCMD 
+ OI 0(SP) ,X'40' VOLIO 
+ svc 3 (XIO) 
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Transmit Intertask Message 


Syntax 


[label] XMIT MESSAGE = { (register) } 


Function 


{expression} 
»PORT= { (register) } 
{expression} 
{'string' } 


[,NOWAIT] [,OTHERTASK] 


Queues the message at the specified address for receipt by 
the owner of the specified message port. The CHECK 
macroinstruction is used to accept receipt of a message. 


Return codes are placed in the word on the stack top as 


follows: 


0 


4 


12 


16 


Successful 


No receiving message port with the specified 
name 


Unable to insert message in receiving port's 
message buffer ('NOWAIT' option only) 


Unable to insert message in receiving port's 
message buffer due to receiving port's use of 
PRIVILEGED option 


Message not transmitted; OTHERTASK option was 
specified and the designated message port 
belongs to the XMIT-issuing task 


Operand Descriptions 


MESSAGE= 


The address of a message, which may be anywhere 
in the issuer's address space. The first two 
bytes of the message area must contain the 
length of the message in binary, including 
these bytes, and may not be greater than 2016. 


May be specified as a register in parentheses 


containing the address of the message, or as_ an 
expression addressing the message. 
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PORT= 
NOWAIT 
OTHERTASK 
Example 

LABL XMIT 
+LAB1 PUSHC 
+ B 
+ DC 
+ PUSH 
+ MVI 
+ SVC 


The four-character name of the receiving 
message port, which may be specified as an 
address expression, or as a register 
designation where the register contains the 
address of the four characters in memory, or as 
a literal value in quotes. 


If specified, return to issuer immediately with 
return code 8 if there is insufficient space in 
the receiving port's message buffer to insert 
the message. 


If specified, return to issuer immediately with 
return code 16 if the designated receiving 
message port belongs to XMIT-issuing task. 


PORT='DBMS' ,MESSAGE= (R2) 
0(4,0) ,*+10 

e+ 

C'DBMS' 

0,R2 

0(15) ,B'00000000' 

36 (XMIT) 


4-142 


CHAPTER 5: CONTROL BLOCKS 


5.1 INTRODUCTION 


This chapter documents the internal control blocks of the VS 
Operating System which are of interest for the general user. The 
following control blocks are described, in Assembler language 
format, and with offset locations: 


AXD1 IORE 
BCE OFB 
BCTBL TPLAB 
EXTRD TPLB2 
FDR1 UFB 
FDR2 VOL1 


Blocks FDR1 and FDR2 constitute part of the disk Volume Table of 
Contents (VTOC), and normally are present on disk only. Blocks 
TPLAB and TPLB2 are tape labels. Block VOL1 is the tape and disk 
volume label. All other blocks are kept in the user's modifiable 
segment (Segment 2), when present. 


The control blocks change frequently. They can be assembled by 
the user with the following lines of code: 


<ctl block> 
END 


where <ctl block> is replaced by a block name. 


A second set of control blocks, intended for operating system use 
only, is kept in the protected system memory segment 
(Segment 0). They consist of the following blocks: CMSG, DBTB, 
DPT, ETCB, FLUB, FMSG, LCB, MCB, PFB, PFSA, PFI, PPB, PRB, PT, 
PXE, RMSG, STMB, SVCT, TCB, TQEL, UCB, and VCB. These control 
blocks are described in a separate document. 
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AXD1 


000000 


000000 
000000 


000004 


00000C 


000010 
000011 


000012 


000013 


THE ALTERNATE INDEX DESCRIPTOR BLOCK (AXD1) DESCRIBES THE 
ALTERNATE INDEX STRUCTURES OF AN INDEXED FILE. AN INDEXED 
FILE HAS AN AXD1 BLOCK IF AND ONLY IF FLAG FDR1IFLAGSALTX 

IS SET IN ITS LABEL (FDR1). THE AXD1 BLOCK CONTAINS 

UP TO 16 (64) ALTERNATE INDEX DESCRIPTIONS (AXD1ENTRY)*. THE 
NUMBER OF DESCRIPTIONS IS CONTAINED IN FDRIALTXCNT OF THE 


IS LOCATED IN BLOCK NUMBER ZERO OF THE FILE. 


1. BLOCK DESIGNATOR AREA (AXD1BL) 
2. DMS PROCESSING AREA (AXDIMASK TO AXD1ENTRY) 
3. AXD ENTRIES (ONE AXD ENTRY PER ALT-INDEX) 
4. SPARE AREA (UP TO END OF 2K BLOCK) 
AREAS 1-3 ARE HELD IN THE AXD1~AREA (POINTED TO BY UFBALTPTR) 


OF 
BL4 BLOCK TYPE DESIGNATION 
AXDBL1 MUST EQUAL XL4'2' 


BL8 BITS ON INDICATE ALTERNATE 


AXD1 
AXD1 DSECT 
* 
% 
* 
* 
* 
* 
¥ 
* FDR1 RECORD. 
¥% 
* THE AXD1 
* THE AXD1 IS DIVIDED INTO 4 AREAS: 
¥ 
* 
* 
¥ 
* 
* DURING FILE PROCESSING. 
% 
¥ DATE 3/28/79 
% VERSION 4.0 
ve 
* BLOCK DESIGNATOR AREA: 
AXD1BEGIN DS 
AXDIBL DS 
¥ 
* 
* DMS PROCESSING AREA: 
AXDIMASK DS 
* 


Se 


AXD1UFB DS 
% 

AXDIALTINX DS 
AXD1FLAGS DS 
AXD1FLAGSOK EQU 
* 

* THE FOLLOWING FLAGS ARE USED 


AXD1FLAGSQ. EQU 
AXD1FLAGSTYPER EQU 
AXDIFLAGSTYPEV EQU 
weve 

AXDIMSIZE DS 
* 

* 

AXD1DUPINX DS 


ve 


INDEX STRUCTURES (NUMBERED 
1 TO 16) PRESENT 
(INITIAL IMPLEMENTATION OF 
2-BYTE MASK ONLY) 
A POINTER TO UFB FOR THIS FILE 
AFTER THE FILE HAS BEEN OPENED 
BL1 ORDINAL INDEX NUMBER FOR READ 
BL1 DMS FLAG BYTE 
X'80' ALTERNATE INDEX STRUCTURES HAVE 
BEEN CREATED WHEN FLAG SET 
FOR DMS PROCESSING (0 IN LABEL) 
X'04' START QUALIFIED OPTION 
X'02' TYPE R SAVEAREA IN USE 
X'01' TYPE V SAVEAREA IN USE 


BL1 SIZE OF MASK PER FILE 
VALUE FROM 2-8 BYTES (MUST BE 2 
FOR FIRST IMPLEMENTATION) 

BL1 ORDINAL INDEX NUMBER OF THE 
ALT-TREE HAVING DUPLICATED KEY 


000014 
000024 


00002C 
00002E 
00002F 
000032 
000035 


000038 
00003A 


00003C 
00002C 
000030 
000032 
00002C 
00002D 
000030 
000032 
000034 
000037 
000038 


00003A 


AXD1 


* MINIMUM AXD1-AREA FOR SHARED MODE ENDS HERE. 


* AXDIMASK, AXDIMSIZE, AND AXDIALTINX ARE REQUIRED. 
% 


AXD1BCB DS BL16 BCB FOR DMS PROCESSING (SEE UFB) 
AXD1PMASK DS BL8 MASK OF VALID ALTERNATE ACCESS 
* PATHS (SET AT FILE CREATION ONLY) 


* 
* THE FOLLOWING FIELDS ARE INTERMEDIATE OUTPUT MODE FIELDS 
* 


AXDIORECSIZE DS H WORK RECORD - MAX LENGTH 
AXD10FLAGS DS BL1 OUTPUT FLAGS (RESERVED) 
AXD1OSTART DS BL3 FIRST BLOCK CONTAINING WORK RECORDS 
AXD1ONRECS DS BL3 TOTAL COUNT OF WORK RECORDS 
AXD1LOEBLK DS BL3 LAST USED BLOCK NUMBER IN PRIMARY 
* TREE (ALT-TREE TO AXD1EBLK+1) 

DS H USED FOR AXDIADMSMASK (SEE BELOW) 
AXD1OSPARE DS BL2 RESERVED IN OUTPUT MODE 
tet 

ORG AXDLORECSIZE 
* THE FOLLOWING FIELDS ARE USED FOR DMS PROCESSING (EXISTING FILES) 
id 
AXD1SAVEADR DS A SAVE AREA ADDRESS (TYPE V) 
AXD1SAVELTH DS H_ SAVE AREA LENGTH (TYPE V) 
ORG AXDLORECSIZE 

* THE FOLLOWING 3 FIELDS ARE USED FOR SAVE AREA TYPE S 
AXD1SKEYSIZE DS BL1 SAVED PRIMARY KEYSIZE 
AXD1SHXBLK DS BL3 SAVED PRIMARY ROOT BLOCK NUMBER 
AXD1SEREC DS 4H SAVED PRIMARY LEVEL COUNT 
* 
AXD1ENTOFF DS 4H OFFSET OF ACTIVE AXDIENTRY (IN AXD1) 
AXD1PTRN DS BL3 NEXT SEQUENTIAL BLOCK (ALT-TREE) 
AXD1CURINX DS BL1 ORDINAL NUMBER -ASSOCIATED WITH 
* BLOCK IN AXD1BCB | 
AXD1ADMSMASK DS 4H ALTERNATE INDEX PATH MASK WITHIN 
* THE VIEW (ADMS USE ONLY) 
AXD1EXSPARE DS BL2 SPARE - ALL FILES 
tte 


%* 
WUE TRIRTREROTRCTTTREEETTEEREICCTRAERLTTTCRTRERTCRITR ICES 


* AXDIMASK AND AXDIALTINX ARE THE ONLY FIELDS IN THE AXD1-AREA WHICH 
* MAY BE MODIFIED BY THE USER-PROGRAM WHILE THE FILE IS OPEN. 


FOR EXISTING FILES, NO FIELDS IN THE AXD1~AREA ARE USER-SUPPLIED 
PRIOR TO ISSUING SVC OPEN. 


AXDIMSIZE (THE ACCESS MASK PREFIX SIZE) 3 
AXDIKEYPOS, AXDIKEYSIZE, AXDIEFLAGS, AND AXD1XORD 


FOR EACH AXDIENTRY (COUNT IN UFBALTCNT) . 
PIAA AAAI IIIA IIIA OTA ATA IAI AOA IAA OI AAI AAAS AAAI 


% 
* 
* FOR OUTPUT MODE, USER-PROGRAM FILLS IN THE REQUIRED AXD1-AREA WITH: 
* 
% 
* 


AXD1 


00003C 


00003C 


00003D 


00003E 


000040 
000042 
000043 


000046 
000049 


00004C 


000058 
00073C 


* 
* AXD ENTRIES: 


AXDLENTRY 
* 


* 

¥ 
AXD1XORD 
* 

# 

* 
AXDLEFLAGS 


AXD1EFLAGSDUPS 
AXD1EFLAGSKCOM 
* 


DS 


DS 


DS 


OXL28 UP TO 64 ENTRIES 


HL1 


BL1 


(EACH A DESCRIPTION OF ONE 
ALTERNATE INDEX STRUCTURE; 

UNUSED ENTRIES ZERO-FILLED) 
ORDINAL NUMBER (STARTING FROM 1) 
IDENTIFYING THIS INDEX STRUCTURE 
(CORRESPONDS TO BIT IN 

AXD1MASK) 

OPTION FLAGS 


EQU X'80' DUPLICATE KEYS ALLOWED 
EQU X'40' KEY COMPRESSION IN INDEX 


(NOT IN FIRST VERSION) 


* THE FOLLOWING FLAGS ARE USED FOR DMS PROCESSING (0 IN LABEL) 
EQU X‘'02' INDICATES THIS ALT-TREE IS THE 


AXD1LEFLAGSACT 
* 


AXD1EFLAGSUP 
* 


¥ 
AXD1XLEVELS 
% 


* 


AXD1LKEYPOS 
AXD1KEYSIZE 
AXD1HXBLK 


AXDINRECS 
AXD1PTRD 
* 


vw 
AXD1ESPARE 
AXDLENTRYEND 


AXDLENTRYLENGTH 
* 


AXD1SPARE3 
* 


AXD1END 
AXD1 LENGTH 


ACTIVE ALT~TREE DURING PROCESSING 


EQU X'01' INDICATES AXDIPTRD, AXD1XLEVELS 


DS 


DS 
DS 
DS 


DS 
DS 


DS 


H 


H 
HL1 
FL3 


BL3 
FL3 


OR AXDILHXBLK HAS BEEN MODIFIED 
DURING ALT-TREE PROCESSING 
NUMBER OF LEVELS OF THIS 
ALTERNATE INDEX STRUCTURE 
EXCLUDING LOWEST LEVEL 

KEY POSITION IN RECORD 
KEY LENGTH 

BLOCK-~IN-FILE OF ROOT BLOCK 

OF THIS ALTERNATE INDEX 

ITEM COUNT - LOW LEVEL OF TREE 
FIRST BLOCK OF LOW LEVEL 

OF THIS ALTERNATE INDEX 
(ALTERNATE KEY SEQUENCE) 


BL12 (RESERVED IN EACH ENTRY) 
EQU * 
EQU AXDIENTRYEND-AXD1ENTRY 


ORG AXDLENTRY+64“L' AXDIENTRY 
DS XL196 (RESERVED) 


EQU * 
EQU AXD1END-AXD1BEGIN 


000000 


000000 
000000 
000004 
000004 
000008 
QO0000A 
00000C 


OOOOOF 


000010 


00001C 


00001D 
OOO01E 
00001F 
000020 


000024 


000030 


BCE 


BCE 
BCE DSECT 
* 
* THE BUFFER CONTROL ENTRIES (BCE) ARE CONTAINED IN THE BUFFER 
* CONTROL TABLE (BCTBL). THERE IS ONE BCE PER 2K BUFFER IN A 
* DATA MANAGEMENT BUFFER POOL. BCTNBUF (WHICH AGREES WITH 
% OFBBCOUNT FOR AN ACTIVE BUFFER POOL) INDICATES THE NUMBER 
* OF BUFFER CONTROL ENTRIES PER BCTBL. 
¥* 
* DATE 3/28/79 
* VERSION 4.00 
* 
BCEBEGIN DS OF (FULLWORD ALIGNMENT) 
BCEOFB DS A OFB ADDRESS 
BCEBUFCMD DS OBL1 COMMAND BYTE 
BCEBUFADR DS A BUFFER MEMORY ADDRESS 
BCEBUFDATAL DS H IO-LENGTH (2K) 
BCESPARE DS H OFFSET (UNUSED IN BCE) 
BCEBUFBLOCK DS FL3 BLOCK WITHIN 
* FILE OF BUFFERED DATA 
BCEBCBFLAGS DS BL1 FLAGS 
BCEBCBFLAGSLOD EQU x'O1' BUFFER CONTENTS VALID 
BCEBCBFLAGSTOR EQU x'02' BUFFER TO BE REWRITTEN 
BCEBCBFLAGSIO EQU X'04' BUFFER I/O IN PROGRESS 
BCEBCBFLAGSREF EQU x'80' REFERENCE BIT 
* BIT=1 ON ANY READ/WRITE 
BCEKEYHI DS CL12 TRUNCATED HI KEY VALUE 
* (TYPE D) 


* BLOCK TYPE (BCETYPE) CONTAINS INTERNAL AND EXTERNAL VALUES 
* DEPENDING ON FILE ORG (INDEXED FILES HAVE **** NO *#*** BLOCK TYPE 
* BYTE IN THE BLOCK; THUS I,D,A BELOW ARE INTERNAL TYPES.) 


BCETYPE DS CL1 BLOCK TYPE (ASCII CHAR) 

* BLOCK TYPE VALUES (INTERNAL) FOR INDEXED FILES 

BCETYPEI EQU C'I' INDEX BLOCK 

" (CONTAINS INDEX ITEMS) 
BCETYPED EQU C'D' DATA BLOCK 

* (CONTAINS DATA RECORDS) 

= BCEKEYHI/LOW SET IF TYPE = 
BCETYPEA EQU C‘'A' AVAILABLE BLOCK (CHANGED TO 
¥ TYPE I OR D IF USED 

* BY BLOCK SPLIT) 

BCETYPES EQU c'sS' BLOCK FROM LOW-LEVEL OF AN 
* ALTERNATE TREE 

BCEWT DS BL1 STARTING WEIGHT VALUE 
BCEAGEWT DS BL1 AGED WEIGHT VALUE 

BCESPARE1 DS BL1 SPARE 

BCEIOCHN DS A CHAIN FOR BCE'S WITH I/O 

* IN PROGRESS 

BCEKEYLOW DS CL12 TRUNCATED LOW KEY VALUE 

¥ (TYPE D) 
BCEEXPAND DS BL8& BCE EXPANSION 

* EXPANSION = 12 (TRUNC KEYS =12), PLUS 4 (CHN BCE PER UFB)+4 EXTRA 
BCELENGTH EQU *-BCEBEGIN BCE LENGTH (=56) 


375 


D 


BICBL 


000000 


000000 


000000 
000000 
000004 
000008 


000008 
00000C 
00000D 


OOOO00E 


OOOO0F 
000010 


000014 


00001C 
000014 
000015 
000016 
000017 
000018 
000019 
00001A 
00001B 
00001C 


000020 
000058 


BCTBL 
BCTBL DSECT 
* 
% THE BUFFER CONTROL TABLE (BCTBL) IS ADDRESSED FROM THE USER 
* FILE BLOCK (UFB) , AND CONTAINS A HEADER DEFINING A DATA 
* MANAGEMENT BUFFER POOL AND BUFFER CONTROL ENTRIES (BCE) 
¥ DEFINING THE CONTENTS OF EACH BUFFER IN THE POOL. 
* 
% DATE 3-28-79 
¥ VERSION 4.00 
% 
BCTBLBEGIN DS OF (FULLWORD ALIGNMENT) 
* 


*#* BUFFER CONTROL TABLE 
#e 


BCTBLNBUF DS  OHLI1 COUNT OF BUFFERS (BCE'S) 


BCTBLHITCT DS A HIT-COUNT (READ) 
BCTBLLOCK1 DS A BCE LOCK1 (DMS INTERNAL) 
BCTBLREPLNUM DS  OHLi CIRCULAR BCE NUMBER (SCAN) 


* BCTBLHITCT AND BCTBLMISSCT INDICATE PERCENTAGE OF READ OPERATIONS 
* HANDLED WITHIN THE BUFFER POOL (WITHOUT PHYSICAL IO OPERATION). 


BCTBLMISSCT DS A MISS-COUNT (READ) 
BCTBLFILECT DS BLI1 COUNT OF FILES USING BCT 
BCTBLFLAGS DS BLL BCTBL FUNCTION FLAGS 
BCTBLFLAGSEXT EQU xX'80' INTERNAL FLAG FOR 

¥ EXTRACT FUNCTION 
BCTBLFLAGSRPL EQU xX'40' GET REPLACEMENT BUFFER 
¥e WITHOUT IO OPERATION 
BCTBLTYPE DS CLI BLOCK TYPE FOR FUNCTION 
= (VALUE AS IN BCETYPE) 
BCTBLSPARE DS BLL SPARE 

BCTBLIOHEAD DS A HEAD OF CHAIN FOR BCES 
* WITH I/O OUTSTANDING 
BCTBLWTABLE DS XL8 TABLE OF WEIGHTS FOR REPL 


* VALUE IN PAREN BELOW IS DEFAULT VALUE LOADED BY SVC OPEN. 
ORG BCTBLWIABLE 


BCTBLWDATA DS XLi DATA BLOCK NO HOLD (1) 
BCTBLWDATAH DS XL1 DATA BLOCK HOLD (2) 
BCTBLWINDEX DS XL1 INDEX BLOCK (PRIMARY) (3) 
BCTBLWROOT DS XL1 INDEX ROOT (PRIMARY) (5) 
BCTBLWADATA DS XL1 LOW LEVEL ALT BLOCK (1) 
BCTBLWAINDEX DS XL1 INDEX BLOCK (ALT) (3) 
BCTBLWAROOT DS XL1 INDEX ROOT (ALT) (5) 
BCTBLWRES DS XL1 RESERVED WEIGHT CLASS (0) 
BCTBLEXPAND DS BL4 EXPANSION AREA (BCTBL) 
* END OF BCTBL HEADER; BCE'S BEGIN HERE 

BCTBLBCE1 DS BL56 BUFFER CONTROL ENTRY 
BCTBLBCE2 DS BL56 BUFFER CONTROL ENTRY 2,ETC 
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000000 


000000 


000000 
000000 


000004 


000006 


000008 


00000C 
000000 


000000 
00000C 
000010 
000010 
000016 
000016 
OQOO01E 
OOOO1E 


000020 
000020 
000026 
000026 
00002E 
000032 
000032 
000038 
000038 
000040 
000044 
000044 
00004A 
00004A 
000052 


EXTRD 
EXTRD DSECT 
* 
% SYMBOLIC. DEFINITION OF THE RESULT AREA OF THE 'EXTRACT' 
* SUPERVISOR ROUTINE, AND ID CODES FOR CLASS 3 AND 4 EXTRACT 
* ITEMS 
¥% 
* DATE 5/27/79 
* VERSION 2.01 (INCLUDES 2246C WORKSTATION) 
¥ 
EXTRDBEGIN DS OXL1 (UNALIGNED) 
¥ 
EXTRDIDMAX EQU 73 MAX ID # CURRENTLY IN 114 
* USE-FROM EXTRACT MACRO 11% 
MRNA ERARRREERECT ASS QUAI ITEC EIR OHTA AAI ICR, 
EXTRDCLASSO DS OXL12 RETURNED FOR CLASS 0: 
EXTRDNRES DS AL4 PHYSICAL MEMORY (BYTES) 
* NOT PERMANENTLY RESIDENT 
EXTRDOCNT DS HL2 NUMBER OF FILES WHICH 
* CURRENT TASK MAY HAVE 
* OPEN, EXCLUDING FILES 
* ALREADY OPEN 
EXTRDWS DS HL2 TASK'S ASSOCIATED 
* WORKSTATION NUMBER, OR 
* -1 IF NONE 
EXTRDSTACK DS AL4 REMAINING STACK SPACE 
¥* 
WURMAARRCARERALNAIEAACLA SS YELTSIN, 
ORG EXTRDBEGIN 
EXTRDCLASS1 DS OXL98 RETURNED IN ADDITION 
* FOR CLASS 1: 
ORG EXTRDBEGIN+L' EXTRDCLASSO 
EXTRDDYVAL DS FL4 ONE DAY IN CLOCK UNITS 
EXTRDSYSVOL DS OCL6 SYSTEM DEFAULT LIBRARY 
EXTRDSCDVOL DS CL6 VOLUME NAME 
EXTRDSYSLIB DS OCL8& SYSTEM DEFAULT LIBRARY 
EXTRDSCDNAME DS CL8 NAME 
EXTRDPRINTER DS OHL2 DEFAULT ONLINE PRINTER 
EXTRDDEFPRT DS HL2 DEVICE NUMBER, 
* OR -1 OF NONE 
EXTRDRUNVOL DS OCL6 
EXTRDUPDVOL DS CL6 USER PROGRAM LIB.VOLUME 
EXTRDRUNLIB DS OCL8 . 
EXTRDUPDNAME DS CL8& USER PROGRAM LIB.NAME 
EXTRDEXFLGS DS BL4 "EXECUTE' ACCESS MASK 
EXTRDINVOL DS OCL6 
EXTRDVOL DS CL6 DEFAULT INPUT VOLUME 
EXTRDINLIB DS OCL8 
EXTRDFILE1 DS CL8 DEFAULT INPUT LIBRARY 
EXTRDRDFLGS DS BL4 "READ' ACCESS MASK 
EXTRDOUTVOL DS OCL6 
EXTRDVOLO DS CL6 DEFAULT OUTPUT VOLUME 
EXTRDOUTLIB DS OCL8 
EXTRDFILE10 DS CL8 DEFAULT OUTPUT LIBRARY 
EXTRDWIFLGS DS BL4 "'WRITE' ACCESS MASK 


EXTRD 


000056 


000058 
000058 


000059 
000059 


00005A 
00005D 
00005D 
00005E 
OOO05F 


00005F 


000062 
000000 
000000 


EXTRDSEG2BUF DS BL2 NUMBER OF SEGMENT 2 

* "BUFFER' PAGES 

¥ CURRENTLY AVAILABLE 
EXTRDPRNTMODE DS OCLI1 

EXTRDPRTTYPE DS CL1 PRINT OUTPUT MODE 

+ ('s', 'H', OR 'O') 
EXTRDFILECLAS DS OCL1 

EXTRDFPCLASS DS CL1 DEFAULT FILE PROTECT 

¥ CLASS 

EXTRDUSERID DS CL3 CURRENT USER LOGON ID 
EXTRDTCBSCC DS OHL1 (DO NOT USE) 
EXTRDEXTPRIOR DS HL1 TASK'S PAGING PRIORITY 
EXTRDLINES DS HL1 SUGGESTED LINES/PAGE 
EXTRDSPARE1 DS OBL3 UNUSED PRIOR TO RELEASE 3.1 
* (WAS BINARY ZEROES) 
EXTRDVERSION DS XL3 SYSTEM VERSION NUMBER 
* (SEE EXTRDIDVERSION) 


% 


NAMATH ATARI AR OT A SS QUIT IIIT ITT CLT ICEEN 


ORG EXTRDBEGIN 
EXTRDCLASS2 DS OXL8& RETURNED FOR CLASS 2 
EXTRDPCPCW DS BL8& PROGRAM OLD PCW FOR 
a : LAST PROGRAM CHECK 


¥ 
ERE RARARRAERER RAAT A ss YMA AT AATCC TAME TN CTIA CHL 
* 


+ % 


FOR CLASS 3, ITEM ID CODES ARE SUPPLIED BY THE EXTRACT SVC 
ISSUER AND RETURNED IN INDIVIDUAL AREAS SUPPLIED PER ITEM. 

THE FOLLOWING IS A LIST OF ITEM ID CODES. THE LENGTH OF AN 
ITEM “ITEMID' MAY BE REFERENCED "L'ITEMID". THE TYPE ATTRIBUTE 
MAY BE REFERENCED AS "T'ITEMID". 


+e & % 


tidedcikidticticiccicdcdickiccddccckiccmiccdcadclcccilcidcciccddclsscdelccccdcccdcetccicecick 
* SYSTEM-WIDE INFORMATION: 
widiekticnicididcdcicKrKciiicicnnshKKrKicickKKTcEenicccsKiidlciccicvcscdciictwlcivticwcticictcicvicteict 
¥ 

EXTRDIDNRES EQU 0,4,A PHYSICAL MEMORY (BYTES) 

% NOT PERMANENTLY RESIDENT 


EXTRDIDDYVAL EQU 4,4,F ONE DAY IN CLOCK UNITS 
EXTRDIDSYSVOL EQU 5,6,C SYSTEM DEFAULT LIBRARY 

% VOLUME NAME 
EXTRDIDSYSLIB EQU 6,8,C SYSTEM DEFAULT LIBRARY 

* NAME 

EXTRDIDSY SWORK EQU 24,8,C SYSTEM WORK LIBRARY NAME 

¥ (BACKUP SKIPS) 
EXTRDIDSYSPAGE EQU 60,8,C SYSTEM PAGING LIB NAME 14 
- (BACKUP SKIPS) 14 
EXTRDIDCPU EQU 61,2,H CURRENT CPU ID 1% 
EXTRDIDHZ EQU 62,2,H A/C LINE FREQUENCY 1% 
EXTRDIDVERSION EQU 25,3,X SYSTEM VERSION NUMBER 

* (PACKED VVRRPP, WHERE 

¥ 'vv' IS VERSION 

¥ 'RR' IS REVISION 

* 'pp' IS PATCH LEVEL 
EXTRDIDDEVCNT EQU 56,4,F ## OF DEVICES ON SYSTEM 
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EXTRDIDATOETRT 
* 


EXTRDIDETOATRT 


¥ 


EXTRDCDISKET 
* 


ve 


TIAA IAI AOA IAAI AAAI AAAI IAA ATA AAA AIA AAAI 


* TASK-RELATED INFORMATION: 
Se AAA AAA ATA AAAI ASA AAA AIA ATI AAAI IAT LIISA ALARA IOI 


* 
EXTRDIDOCNT 
* 


* 

* 

EXTRDIDWS 

¥ 

* 

EXTRDIDSTACK 
EXTRDIDEXFLGS 
EXTRDIDRDFLGS 
EXTRDIDWTFLGS 
EXTRDIDUEXFLGS 
EXTRDIDURDFLGS 
EXTRDIDUWTFLGS 
EXTRDIDSEG2BUF 
* 


EXTRDIDUSERID 
EXTRDIDUSERNAME 
EXTRDIDEXTPRIOR 
EXTRDIDPCPCW 

* 

EXTRDIDTASK# 
EXTRDIDTASKTYPE 


+ 


% 


* 


EXTRDIDCURVOL 
EXTRDIDCURLIB 
EXTRDIDWORKLIB 
% 


ry 
EXTRDIDSPOOLIB 
ve 

te 
EXTRDIDJOBNAME 
EXTRDIDSEG2SIZE 
EXTRDIDSTATIC 
ve 


Pid 


ve 


a~9 


EQU 57,256,C 


EQU 58,256,C 


EQU 


EQU 


EQU 


EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 


EQU 
EQU 
EQU 
EQU 


EQU 
EQU 


EQU 
EQU 
EQU 


EQU 


EQU 
EQU 
EQU 


66,2,H 


1,2,H 


EXTRD 


ASCII-TO-EBCDIC 

TRANSLATE TABLE 

EBCDIC—TO-ASCII 

TRANSLATE TABLE 

DEVICE # OF SYSTEM'S 064 
CENTRAL DISKETTE 06% 


NUMBER OF FILES WHICH 
CURRENT TASK MAY HAVE 
OPEN, EXCLUDING FILES 
ALREADY OPEN 

TASK'S ASSOCIATED 
WORKSTATION NUMBER, OR 
-1 IF NONE 

REMAINING STACK SPACE 

‘EXECUTE’ ACCESS MASK 

"READ' ACCESS MASK 

‘WRITE' ACCESS MASK 

USER'S ‘EXECUTE' ACCESS 2% 

USER'S ‘READ’ ACCESS 2% 

USER'S 'WRITE' ACCESS 24 

NUMBER OF SEGMENT 2 
‘BUFFER’ PAGES 
CURRENTLY AVAILABLE 

CURRENT USER LOGON ID 

USER NAME (FROM USERLIST) 

TASK'S PAGING PRIORITY 

PROGRAM OLD PCW FOR 
LAST PROGRAM CHECK 

UNIQUE TASK IDENTIFIER 

TASK TYPE: 

'F ' FOR FOREGROUND 
'FS' FOR DEDICATED 
SYSTEM TASK (FG) 
'B ' FOR BACKGROUND 
'BS' FOR DEDICATED 
SYSTEM TASK (BG) 

VOLUME OF CURRENT PROGRAM 

LIBRARY OF CURRENT PROGRAM 

WORK LIBRARY NAME 
CONTRUCTED FROM USER ID 
OR BG TASK # 

SPOOL LIBRARY NAME 
CONSTUCTED FROM USER ID 
OR BG TASK # 

NAME OF BACKGROUND JOB 8% 

LENGTH OF SEG 2 IN BYTES 

ADDRESS OF START OF STATIC 
AREAS (R14 AT PROGRAM 
INVOCATION) 


EXTRD 


WITHIN ICN CANTINA ITC ICA TTT CECT ICCC ICCC ETE RECTE HTH, 
% USER DEFAULTS. MAY BE SET USING SET SVC. 

WCRI TIT TRTEEIIETEENRITTECTEE A EETCRACCTCRATERTEEEIRICREEC ERNIE 
* 


EXTRDIDPRINTER EQU 7,2,H DEFAULT ONLINE PRINTER 

* DEVICE NUMBER, 

* OR -1 IF NONE 
EXTRDIDRUNVOL EQU 8,6,C USER PROGRAM VOLUME 

* USED BY CP RUN COMMAND 
EXTRDIDRUNLIB EQU 9,8,C USER PROGRAM LIBRARY 

% USED BY CP RUN COMMAND 
EXTRDIDINVOL EQU 11,6,C DEFAULT INPUT VOLUME 
EXTRDIDINLIB EQU 12,8,C DEFAULT INPUT LIBRARY 
EXTRDIDOUTVOL EQU 14,6,C DEFAULT OUTPUT VOLUME 
EXTRDIDOUTLIB EQU 15,8,C DEFAULT OUTPUT LIBRARY 
EXTRDIDPRNTMODE | EQU 18,1,C PRINT OUTPUT MODE 

ve CS; 'H', ‘o*; OR "K') 
EXTRDIDFILECLAS EQU 19,1,C DEFAULT FILE PROTECT 

* CLASS 

EXTRDIDLINES EQU 22,1,H SUGGESTED LINES/PAGE 
EXTRDIDPROGVOL EQU 35,6,C USER PROGRAM VOLUME 

* USED BY LINK SVC 
EXTRDIDPROGLIB EQU 36,8,C USER PROGRAM LIBRARY 

= USED BY LINK SVC 
EXTRDIDWORKVOL EQU 37,6,C DEFAULT WORK VOLUME 
EXTRDIDSPOOLVOL EQU 38,6,C DEFAULT SPOOL VOLUME 
EXTRDIDPRICLASS EQU 39,1,C DEFAULT PRINT CLASS FOR 

* PRINT FILES (A-Z) 
EXTRDIDFORM# EQU 40,1,H DEFAULT FORM NUMBER FOR 

* PRINT FILES (0-254) 
EXTRDIDJOBQUEUE EQU 68,1,C DEFAULT JOB STATUS 84 
% C'R' OR 'H') 84 
EXTRDIDJOBCLASS EQU 69,1,C DEFAULT JOB CLASS 84 
* C'A' TO 'Z') 8% 
EXTRDIDJOBLIMIT EQU 70,4,F DEFAULT JOB CPU TIME 84 
* LIMIT (SECONDS) 84 


% 
VORTICES ARABTEC LILIA AA ASOD INTEC 
* RUN STATISTICS 

DPE TIRE TRITIATED PERL CPE CP CBCP CPN CL ORCL OTC CRTCATTCS TOTTI 
¥ 


EXTRDIDWSIO EQU 41,4,F COUNT OF WORKSTATION IOS 

* THIS RUN 

EXTRDIDTAPEIO EQU 42,4,F COUNT OF TAPE I0S THIS RUN 
EXTRDIDDISKIO EQU 43,4,F COUNT OF DISK I0S THIS RUN 
EXTRDIDPRINTIO EQU 44,4,F COUNT OF PRINTER I0S 
EXTRDIDOTIO EQU 45,4,F COUNT OF OTHER I0S 
EXTRDIDPICOUNT EQU 46,4,F PROGRAM PAGEIN COUNT 
EXTRDIDPOCOUNT EQU 47,4,F PROGRAM PAGEOQUT COUNT 
EXTRDIDSICOUNT EQU 48,4,F SYSTEM PAGEIN COUNT 
EXTRDIDSOCOUNT EQU 49,4,F SYSTEM PAGEOUT COUNT 
EXTRDIDETIME EQU 50,4,F ELAPSED TIME OF RUN SINCE 
% COMMAND PROCESSOR 

* INITIATION, IN 

* HUNDREDTHS OF SECONDS 
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000008 
000000 


000001 


EXTRDIDPTIME 
* 


% 


* 


EQU 51,4,F 


EXTRD 


PROCESSOR TIME OF RUN 
SINCE COMMAND PROCESSOR 


INITIATION, IN 


HUNDREDTHS OF SECONDS 


IAA AAAI CLASS  Gitciiit dt dtd ddI AAAIAT AAAI 


* 


* CLASS 4 ITEMS ARE SIMILAR TO CLASS 3 ITEMS, EXCEPT THAT 
* ADDITIONAL INPUT IS REQUIRED PER ITEM. 

* 

EXTRDIDDEVICE EQU 52,24,B 


%* INPUT 
*  QUTPUT AS FOLLOWS: 


ORG EXTRDBEGIN 


EXTRDDEVCLASS 
EXTRDDEVCLASSWS 
EXTRDDEVCLASSMT 
EXTRDDEVCLASSDK 
EXTRDDEVCLASSPR 
EXTRDDEVCLASSTC 
EXTRDTYPE 
EXTRDTYPE2246P 
EXTRDTYPE2246S 
EXTRDTYPE2246R 
EXTRDTYPE2246C 
EXTRDTYPE224 6K 
EXTRDTYPE2266C 
EXTRDTYPE2266S 
EXTRDTYPE2246S1 
EXTRDTYPE2246D 
EXTRDTYPE2256C 
EXTRDTYPE227 6C 
EXTRDTYPE22460 
EXTRDTYPE2246CI 
EXTRDTYP2246SIK 
EXTRDTYPE224 6RK 
* 
EXTRDTYPE8021 
EXTRDTYPE2209V 
* 


EXTRDTYPE2209V2 
% 


EXTRDTYPE2209V3 
EXTRDTYPE2260V 
EXTRDTYPE2265V1 
EXTRDTYPE2265V2 
EXTRDTYPE2270V 
% 


EXTRDTYPE2280V1 
EXTRDTYPE2280V2 
EXTRDTYPE2280V3 
EXTRDTYPE2270V1 
¥ 


EXTRDTYPE2270V2 
* 
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DS 

EQU 
EQU 
EQU 
EQU 
EQU 
DS 

EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 


EQU 
EQU 


EQU 


EQU 
EQU 
EQU 
EQU 
EQU 


EQU 
EQU 
EQU 
EQU 


EQU 


= DEVICE ADDRESS (1 BYTE) 


HL1 


031 


033 
034 


035 


036 
050 
051 
052 
053 


054 
055 
056 
057 


058 


DEVICE CLASS: 
WORKSTATION 
MAGNETIC TAPE 
DISK 
PRINTER 


9% 
9% 
9% 
9% 


TELECOMMUNICATIONS 9% 


DEVICE TYPE: 


2246P j§ WORKSTATION 
2246S WORKSTATION 
2246R | WORKSTATION 
2246C j§ WORKSTATION 
2246K WORKSTATION 


ARCHIVER C W/S 
ARCHIVER S W/S 


9% 

9% 

9% 

94 
049% 
3A494 
3A494 


IDEQGRAPHIC S W/S 749%14% 


IBM 029 S W/S 

64K C W/S 

ARCHIVER C 64K wW/S 
OKIDATA WORKSTATION 
IDEOGRAPHIC C W/S 
IDEOGRAPHIC/K S W/S 
REMOTE KATAKANA W/S 


8021 MAG TAPE (800 
2209V MAG TAPE 
(1600 BPI) 
2209V-2 MAG TAPE 
(800/1600 BPI) 
2209V-3 7-TRACK MAG 
2260V DISK (408CYL 
2265V-1 DISK (823CYL 
2265V-2 DISK (823CYL 
2270V. =‘ DISKETTE 
(77CYL REM) 
2280V-1 DISK (823CYL 
2280V-2 DISK (823CYL 
2280V-3 DISK (823CYL 
2270V-1 DISKETTE 
(HARD SECTORED) 
2270V-2 DISKETTE 
(SOFT SECTORED) 


104 
124 
124 
124 
144 
144 
144 


BPI) 94 
9% 


9% 
TAPE9* 


F/R) 94 
REM) 9% 


REM) 9% 


9% 


F/R) 9% 
F/R) 9% 
F/R) 94 


EXTRD 


EXTRDTYPE2270V3 
% 


EXTRDTYPE9614 
* 


‘EXTRDTYPE2221V 
* 


EXTRDTYPE2231V2 
EXTRDTYPE2261V 
EXTRDIYPE2263V1 
EXTRDIYPE2263V2 
EXTRDTYPE8047 

¥ 

EXTRDTYPE6048 
EXTRDTYPE2261V 
EXTRDTYPE2231V6 
EXTRDTYPE2263V3 


* 


EXTRDTYPE2273V1 
v 


Weiss 


EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 


EQU 


059 
060 
065 
067 
068 
069 
070 
071 
072 
073 
074 
075 


076 


2270V-3 DISKETTE 03494 
(HARD OR SOFT SECTORED) 03% 


wie (SERIAL PRINTERS -- TENTATIVE PRODUCT NUMBERS ) **%*« 


Kiet 


EXTRDTYPE2221VS 
* 


EXTRDTYP2231V2S 
* 
EXTRDTYPE2261VS 
* 
EXTRDTYP2263V1S 
* 


EXTRDTYP2263V28S 


* 


EXTRDTYPE2281VS 
* 


EXTRDTYPE6581W 


% 


EXTRDTYP2231V6S 
¥ 


EXTRDTYP2263V3S 


ray 


EXTRDTYPE 6581WC 
% 

EXTRDTYPE5573 

¥ 

EXTRDTYPE5574 

¥ 


EXTRDTYPE5521K 
ve 


EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 


EQU 
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097 
099 
100 
101 
102 
105 
105 
106 
107 
108 
109 
110 


111 


9614 FIXED DISK 4494 
2221V PRINTER > o4 
(200CPS MAT) 
2231V-2 PRINTER 94 
(120CPS MAT) 
2261V PRINTER 9% 
(240LPM MAT) 
2263V-1 PRINTER 94 
(300LPM TR) 
2263V-2 PRINTER 94 
(600LPM TR) 
8047 PRINTER 94 
(225LPM TR) 
8048 PRINTER 94 
(450LPM TR) 
2281V PRINTER (30CPS 9% 
DAISY WHEEL) 
2231V-6 PRINTER 94 
(120 CPS MATRIX) 
2263V-3 PRINTER 94 
(430 LPM TR) 
2273V-1 PRINTER 079% 
(REMOTE) 0% 
tetets 
Fetete 
2221V-S PRINTER 9% 
(200 CPS MATRIX) 
2231V-2S PRINTER 94 
(120 CPS MATRIX) 
2261V-S PRINTER 94 
(240 LPM MATRIX) 
2263V-1S PRINTER 94 
(300 LPM TR) 
2263V-2S PRINTER 94 


(600 LPM TR) 
2281V-S PRINTER (30CPS 9% 


DAISY WHEEL) 
6581W PRINTER 0794 
( 30 CPS DAISY) O* 
2231V-6S PRINTER 94 
(120 CPS MATRIX) 
2263V-3S PRINTER 94 
(430 LPM TR) 
6581-WC WIDE PRINTER 049% 
( 40 CPS DAISY ) O* 
5573 PRINTER 0794 
(300 LPM BAND) O* 
5574 PRINTER 0794 
(600 LPM BAND) O* 
5521K KATAKANA PRINTER4%9% 
(200 CPS MATRIX) 44 


000002 


000004 


000008 


OO000E 


000014 


000018 


000000 


000001 


000002 


000004 


EXTRD 


EXTRDTYPE55312K EQU 112 5531-2K KATAKANA PRT 4494 
id (120 CPS MATRIX) 4A 
EXTRDTYPE5548Z EQU 113 5548Z TYPESETTER 4494 
* 

EXTRDTYPEIP41D EQU 114 INTELLIGENT IMAGE PRT 5%9%4 
: , 

EXTRDTYPE55211 EQU 115 IDEOGRAPHIC MAT PRT 7494 
% 

EXTRDTYPE5581WD EQU 116 DUAL-HEAD DAISY PRT 124 
* 124 
EXTRDTYPECP210 EQU 117 OKIDATA MATRIX PRT 124 
¥ 12% 
EXTRDTYPE55211K EQU 118 IDEOGRAPHIC/K MAT PRT 14% 
* 144 
EXTRDTYPE1022S EQU 119 180 CPS MAT PRT 144 
* 14% 
detels 

EXTRDTYPETC EQU 081 BATCH TC DEVICE 9% 
ve 

EXTRDDEVUSAGE DS CL2 DEVICE USAGE: 

EXTRDDEVUEX EQU C'EX' EXCLUSIVE USE O64 
EXTRDDEVUSH EQU C'SH' SHARED USE 06+ 
EXTRDDEVUDT EQU C'DT' DETACHED O64 
EXTRDDEVUSER DS AL4 TASK IDENTIFIER OF 

* CURRENT DEVICE OWNER, 

* -1 IF NONE 

EXTRDDEVREM DS CL6 VOLSER OF REMOVABLE VOLUME 
* DEFINED ONLY FOR DISK AND 

* TAPE. CL6' ' IF NOTHING 

* MOUNTED. 

EXTRDDEVFIXED DS CL6 VOLSER OF FIXED VOLUME 

* DEFINED ONLY FOR DISK. 

* CL6' ' IF NOTHING MOUNTED. 
EXTRDDEVSPARE DS CL4 (UNUSED) 


* 

WIR RIRII I TIII LA RI A IOTIRIL EE I A ITLILIIIILI LA ILLLILLIIATOCE. 
* 

EXTRDIDVOLUME EQU 53,24,B 

%* INPUT = VOLUME SERIAL NUMBER (6 BYTES) 

* OUTPUT AS FOLLOWS: 


ORG EXTRDBEGIN 
EXTRDVOLDEV DS ALl DEVICE NUMBER, OR -1 IF 
* VOLUME NOT MOUNTED 
* NOTE: EXTRDVOLTYPE, EXTRDVOLLABEL , 
* EXTRDVOLUSAGE, AND EXTRDVOLUSERID 
% ARE ALL BLANK IF VOLUME IS NOT MOUNTED. 
EXTRDVOLTYPE DS CL1 VOLUME TYPE: 
EXTRDVOLTYPER EQU C'R' REMOVABLE 
EXTRDVOLTYPEF EQU C'F' FIXED 
EXTRDVOLLABEL DS CL2 LABEL TYPE: 
EXTRDVOLLABSL EQU C'SL' STANDARD LABEL 06% 
EXTRDVOLLABNL EQU C'NL' NO LABEL 06% 
EXTRDVOLUSAGE DS CL2 VOLUME USAGE: 
EXTRDVOLUSH EQU C'SH' SHARED USE 06% 
EXTRDVOLURR EQU C'RR' RESTRICTED. . 06% 
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EXTRD 


000006 
00000A 
00000C 


00000E 
000010 


000012 
000014 


000015 


000016 


000018 


000000 


000001 


000004 


00001C 


OOOO1E 


000030 
000000 


000001 


000002 


* . REMOVAL 06% 
EXTRDVOLUPR EQU C'PR' PROTECTED USE 06% 
EXTRDVOLUEX EQU C'EX' EXCLUSIVE USE O6* 
EXTRDVOLUSER DS AL4 TASK IDENTIFIER OF VOLUME 
* MOUNTER, -1 IF NONE 
EXTRDVOLBC DS HL2 BLOCKS PER CYLINDER 
EXTRDVOLMAXTFR DS HL2 MAXIMUM TRANSFER IN BYTES 
EXTRDVOLCV DS HL2 CYLINDERS PER VOLUME 
EXTRDVOLCVP DS HL2 CYLINDERS PER PHYSICAL 

* VOLUME, INCLUDING BAD 

x AND UNUSED BLOCKS 
EXTRDVOLOCNT DS HL2 NUMBER OF FILES OPEN 
EXTRDVOLSECT DS CLI SECTOR TYPE: 3B 
¥ -- DISKETTE ONLY -- 3B 
EXTRDVOLSECTS EQU C'S' SOFT SECTOR 3B 06% 
EXTRDVOLSECTH EQU C'H' HARD SECTOR 3B O64 
EXTRDVOLADDR DS CLI ADDRESSING IN EFFECT: 3B¢4 
* -- DISKETTE ONLY -- 3B% 
EXTRDVOLADDRN EQU C'N' NON-STANDARD 3B 064 
EXTRDVOLADDRS EQU C'S' STANDARD 3B% O64 
EXTRDVOLSPARE DS BL2 (UNUSED) 034 
% 


PetcdsictetetotctedctetcttdentetOt ICBC CTC ACCC ACEC SCC CTCL CPCI CECE ACE EACLE IS Be 
* 
EXTRDIDOTASK EQU 54,48,B 
% INPUT = TASK IDENTIFIER (4 BYTES) 
%* OUTPUT AS FOLLOWS: 
ORG EXTRDBEGIN 


EXTRDOTASKWS DS ALI WORKSTATION DEVICE NUMBER 
bad OF TASK SPECIFIED, 

* OR -1 IF NOT FOREGROUND 
¥ TASK 

EXTRDOTASKUID DS CL3 CURRENT USER ID FOR TASK 

* SPECIFIED, OR BLANK 
EXTRDOTASKNAME DS CL24 CURRENT USER NAME FOR TASK 
* SPECIFIED, OR BLANK 
EXTRDOTASKTYPE DS CL2 TASK TYPE - 

* SEE EXTRDIDTASKTYPE 
EXTRDOTASKSPARE DS BL18 (UNUSED) 


* 
toddcickiclccddddcdccicdctcdccdlccniccctcldicccdccdacddclcciciiciciccciccccccicicicicteictcicicts 
* 
EXTRDIDTAPEVOL EQU 55,20,B 
* INPUT = VOLUME SERIAL NUMBER (6 BYTES) 
* OUTPUT AS FOLLOWS: 

ORG EXTRDBEGIN 


EXTRDTAPEDEV DS AL1 DEVICE NUMBER, OR -1 IF 
* VOLUME NOT MOUNTED 
EXTRDTAPESPAR1 DS BLL (UNUSED) 

v 

* NOTE: EXTRDTAPELABEL, 

* EXTRDTAPEUSAGE, AND EXTRDTAPEUSER ARE ALL BLANK 

* IF NO TAPE MOUNTED. 

EXTRDTAPEDEN DS HL2 TAPE DENSITY IN BINARY 
sid BPI (556,800 OR 1600) 
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000004 


000006 


000008 


00000C 
OOO00E 


000014 
000000 


000001 


000002 
000002 


000003 
000000 
000004 
000006 


000007 
000008 
000009 
00000C 
000014 
00001C 
000022 


000023 
000026 


EXTRDTAPELABEL DS CL? LABEL TYPE: : 
EXTRDTAPELABAL EQU C'AL' ANSI LABEL 06% 
EXTRDTAPELABNL EQU C'NL' NO LABEL 06% 
EXTRDTAPELABIL EQU C'IL' IBM LABEL O64 
EXTRDTAPEUSAGE DS CL2 VOLUME USAGE: 

EXTRDTAPEUSH EQU C'SH' SHARED USE 06% 
EXTRDTAPEUEX EQU C'EX' EXCLUSIVE USE O64 
EXTRDTAPEUSER DS AL4 TASK IDENTIFIER OF VOLUME 
* MOUNTER, —1 IF NONE 
EXTRDTAPEFSEQ DS HL2 FILE SEQUENCE NUMBER 
EXTRDTAPESPAR2 DS BL6 (UNUSED) 


ra 
BEINN IND LTA ARNE RITE NAT ARITREINRTORNTRIER 
¥ 

EXTRDIDDEVLIST EQU 59,3,B 

- INPUT = DEVICE CLASS, AS IN EXTRDDEVCLASS (1 BYTE) 

sid OUTPUT AS FOLLOWS: 


ORG EXTRDBEGIN 

EXTRDDLTOT DS HL1 TOTAL NUMBER OF DEVICES IN 
* SPECIFIED CLASS 
EXTRDDLNUM DS HL1 NUMBER OF DEVICES 
* ADDRESSES SUPPLIED 
EXTRDDLIST DS Ox DEVICE LIST 
EXTRDDLENTRY DS ALI DEVICE ADDRESS, OR X'FF‘ 
* IF NO MORE DEVICES 
tedddctcicicincdcdciccstricnciiccicicKicsiccdviccicsilccvclccccdcccicciciciccwiciciiccdecctccicicteick 
* 
* TC RELATED INFORMATION 114 
EXTRDIDDLPNAME EQU 72,38,B 114 
* INPUT = DLPNAME (4 BYTE CHAR. STRING) 114 
* OUTPUT AS FOLLOWS: 114 
* 114 

ORG EXTRDBEGIN 114 
EXTRDDLPDEVMAP DS XL4 BITMAP OF DEVS ON DLP 11% 
EXTRDDLPDEV#1 DS XL2 1ST DEV ON DLP 114 
EXTRDDLPTYPE DS XLI1 DLP TYPE 114 
EXTRDDLPTYPE1 EQU 1 TYPE 22V06-1 11% 
EXTRDDLPTYPE2 EQU 2 TYPE 22V06-2 114 
EXTRDDLPTYPE3 EQU 3 TYPE 22V06-3 114% 
EXTRDDLPLINECNT DS XL1 ## OF LINES CONTROLLABLE 11% 
* _ BY DLP 114 
EXTRDMCSTATUS DS XL1 MICROCODE FILE STATUS 114 
= 0 - IF STOPPED 114 
* HI BIT ON IF LOADED 11% 
EXTRDDLPSPARE DS XL3 RESERVED FOR FUTURE USE 11% 
EXTRDMCFILE DS XL8 MICROCODE FILE NAME 114 
EXTRDMCLIB DS XL8 MICROCODE LIB NAME 114 
EXTRDMCVOL DS XL6 VOLUME NAME FOR MCFILE 11% 
a 114 
EXTRDDLPRSRV DS XL1 RESERVATION STATUS-DLP 114 
= HI BIT ON IF RESERVED 11% 
EXTRDDLPTASK?# DS XL3 RESERVING TASK # 134114 

ORG , 114 
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EXTRD 


000062 
000000 


000001 
000004 
000008 


000062 
006000 


000002 


000010 


Ici AIA IAI AAAI OA AI AAAI AAAS YOM 


* 11% 
EXTRDIDDLPDEV# EQU 73,8,B 11% 
* INPUT = DEVICE NUMBER (2 BYTES) 114 
* OUTPUT AS FOLLOWS: 11% 
* 114 

ORG EXTRDBEGIN 114 
EXTRDDEVSTATUS DS XL1 DEV RESERVATION STATUS 114 
EXTRDDEVRSRV EQU x'40' DEVICE RESERVED 114 
EXTRDDEVOPEN EQU X'80' DEVICE OPEN 114 
EXTRDDEVTASK# DS XL3 RESERVING TASK # 134114 
EXTRDDEVDLPNAME DS XL4 DLPNAME FOR DEVICE 11% 

ORG , 114 
FRR IIASA IRA IIA IIA IIIA IANA III SOIL IA AITO IK 
- 
* DEVICE CLUSTER INFORMATION 06% 
EXTRDIDCLUSTER EQU 67,16,B 06% 
* INPUT = DEVICE NUMBER (2 BYTES) O64 
* OUTPUT AS FOLLOWS: O64 

ORG EXTRDBEGIN 064% 

EXTRDADISKET DS HL2 DEVICE # OF ASSOCIATED 06% 
bal ARCHIVER DISKETTE, 0O6¢ 
" OR ZERO IF NONE 06% 
EXTRDSPARE DS BL14 (UNUSED) O6t 
* 

ORG 
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FDR1 


FDR | 
000000 FDR1 DSECT 


+ 


THE FORMAT 1 FILE DESCRIPTOR RECORD (FDR1) DESCRIBES THE 


% ATTRIBUTES OF A FILE, INCLUDING THE FIRST THREE EXTENTS 
* OF THE FILE. EVERY FILE ON A VOLUME (EXCEPT THE VTOC 
* AND VOLUME LABEL/IPL TEXT AREA) HAS A FORMAT 1 FDR 
* ASSOCIATED WITH IT. FORMAT 1 FDRS ARE LOCATED THROUGH THE 
* FDX1 AND FDX2 BLOCKS. THERE ARE UP TO 25 80-BYTE 
* FDR RECORDS PER VTOC BLOCK. THE 2045TH BYTE OF A BLOCK 
% CONTAINING FDRS CONTAINS AN ASCII 'F'. ALL BLOCKS CONTAINING 
* AVAILABLE 80-BYTE SLOTS FOR 
* FDRS ARE CHAINED TOGETHER BY BLOCK NUMBERS (WITHIN VTOC, 
¥ FROM 0) IN THE 2047TH AND 2048TH BYTES OF EACH SUCH 
* BLOCK, EXACTLY AS ARE THE FDX2 BLOCKS. 
* THE NUMBER OF AVAILABLE 80-BYTE SLOTS IN A BLOCK 
* IS MAINTAINED IN BINARY IN THE 2043TH AND 2044TH 
* BYTES OF THE BLOCK. 
* 
* DATE 5-17-77 
. VERSION 2.02 (UPDATED FOR ALTERNATE INDEXING) 
* 
000000 FDR1BEGIN DS OF 
000000 FDR1FORMAT DS CLl FORMAT OF FDR (ASCII '1') 
bs ('N' FOR FDR RECORD NOT IN USE) 
FDRLINUSE EQU C'1' FDR1 IN USE 1% 
FDRINOTUSED EQU C'N' FDR1 NOT IN USE 14 
000001 FDR1XTNTCOUNT DS BL1 COUNT OF EXTENTS IN USE 
000002 FDR1ORG | DS BL1 FILE ORGANIZATION 
FDR1LORGCONSEC EQU X'01' CONSECUTIVE ORGANIZATION 
FDR1ORGINDEXED EQU x'02' INDEXED ORGANIZATION 
FDR1ORGWP EQU x‘04' WORD PROCESSING FILE 
FDR1ORGVLEN EQU x'20' VARIABLE-LENGTH RECORDS 
FDR1ORGPRINT EQU x‘40' PRINT FILE 
FDR1ORGPROG EQU X'80' PROGRAM FILE 
000003 FDRIFLAGS DS BL1 FLAGS FOR STATUS 
FDR1FLAGSUPDAT | EQU X'80' SET TO O BY CREATFDR, 
* SET TO 1 BY UPDATFDR 
FDR1FLAGSCOMP EQU x'40' COMPRESSED RECORDS 
FDR1FLAGSRECOV EQU x'20' USE PREFORMAT AND RECOVERY 
* PROCEDURES FOR THIS FILE 
FDR1FLAGSALTX EQU x'10' INDEXED FILE HAS AN AXD1 
* BLOCK AND ALT-INDICES IF SET 
FDR1FLAGSLOG EQU Xx'08' CONSEC LOG FILE FLAG 
FDR1FLAGSPART EQU x'04' PARTIAL BACKUP FILE 
FDR1FLAGSADMS EQU x'02' ADMS FILE 
FDR1IFLAGSPRIV EQU x‘01' PROGRAM FILE CARRIES 
* ADDITIONAL ACCESS PRIVILEGES 
000004 FDR1X1PTR DS H FDX1 BLOCK * 169 + FDX1 
* ITEM IN BLOCK (FROM 0)000006 
FDR1FILENAME DS CL8 MEMBER NAME 
QOOOOE FDRIFILESECTION DS CL1 VOLUME IN A MULTI-VOLUME 
%* FILE (ALWAYS ASCII '1') 
OOOOOF FDRICREDATE DS PL3 CREATION DATE (PACKED YYDDD+ 
000012 FDRIMODDATE DS PL3 LAST MODIFICATION DATE 
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FDR1 


000015 
000018 
000019 


00001C 
00001E 
000020 
000023 
000026 
000029 
00002C 
00002F 


000032 
000034 
000038 
00003A 
00003B 


00003E 


000040 


00004C 
000032 
000033 


000034 
000040 


000040 
000044 


000048 


00004C 


¥ 

FDR1LEXPDATE DS PL3 
FDRLFPCLASS DS CL1 
FDR1CREATOR DS CL3 
* 

FDR1IBLKSIZE DS H 
FDR1SECEXT DS H 
FDR1LX1STRT DS FL3 
FDR1X1END DS’ FL3 
FDR1X2STRT DS FL3 
FDR1X2END DS FL3 
FDR1X3STRT DS FL3 
FDR1X3END DS FL3 


(PACKED YYDDD+) 

EXPIRATION DATE (PACKED YYDD 
FILE PROTECTION ACCESS-CLASS 
USER LOGON IDENTIFICATION OF 
FILE CREATOR 

PHYSICAL BLOCK SIZE (2048) 
NO. BLOCKS SECONDARY EXTENT 
PRIMARY EXTENT START BLOCK 
PRIMARY EXTENT END BLOCK + 1 
2QND EXTENT START 

2ND EXTENT END 

3RD EXTENT START 

3RD EXTENT END 


ee 


%* ORGANIZATION-DEPENDENT SECTION: 


POTTER N TICES 


FDRLSPARE2 DS BL2 
* 

FDR1INRECS DS F 
FDRIRECSIZE DS H 
FDR1LSPARE3 DS BL1 
* 

FDRLEBLK DS FL3 
* 

FDRLEREC DS H 
* 

* 

¥e 

¥ 

FDR1SPARE4 DS BL12 
¥ 

¥ 


(UNUSED FOR CONSECUTIVE 
FILES) 

NUMBER OF DATA RECORDS 
LOGICAL RECORD SIZE 

(UNUSED UNLESS 
FDRIFLAGSALTX SET) 

LAST RECORD'S BLOCK WITHIN 
FILE 

LAST RECORD'S NUMBER IN LAST 
BLOCK FOR CONSECUTIVE FILES 
WITH FIXED-LENGTH RECORDS 
(FOR INDEXED FILES, NUMBER 
OF PRIMARY INDEX LEVELS) 
(UNUSED FOR CONSECUTIVE 
FILES WHICH ARE NOT PROGRAM 
FILES) 


KARWAN ARRAN ERR TERRE RECREATE 


* FOR WORD PROCESSING FILES ONLY: 


MERIT RERRRERIRTTCTTTECE RITTER EERIE TREO 


ORG FDRISPARE2 
FDR1WPBLKSIZE DS XL1 
FDR1IWPBLS DS XL1 
* 


WP FILE BLOCK SIZE 
BYTES IN LAST 
SECTOR 


MRR ERENCE RIOR ROKER EERE EERE RRRETCECEEECTRRERECETE 


* FOR PROGRAM FILES ONLY: 


rr eer ri ee ee sls ee ris tis rie esis rit wit beer c ree es es 


ORG FDRISPARE4 


FDRLACFLAGS DS OBL12 
¥ 

FDRLWIFLAGS DS BL4 
ve 

FDR1IRDFLAGS DS BL4 
v 

FDR1EXFLAGS DS BL4 
we 


ADDITIONAL ACCESS 
PRIVILEGES: 
ADDITIONAL WRITE 
PRIVILEGES 
ADDITIONAL READ 
PRIVILEGES 
ADDITIONAL EXECUTE 
PRIVILEGES 


MURMEREKERRAEBRRAARN AR AACA RABRTE RARER ARAN ERE BREE ERE REECE 


* FOR INDEXED FILES ONLY (FILEORG X'02'): 


MAME RHRERAEAR RAR RURER RARER ERE REAR R TTR 


ORG FDR1SPARE2 
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FDR1 


000032 FDR1PKI DS HL1 PACKING FACTOR FOR INDEX 
* ITEMS 

000033 FDR1PKD DS HL1 PACKING FACTOR FOR DATA 
- RECORDS 

000034 : ORG FDR1SPARE3 

00003A FDRIALTCNT DS HL1 NUMBER OF ALTERNATE INDEX 
* 


STRUCTURES DEFINED IN THE 


% AXD1-BLOCK (UNUSED UNLESS 
* FDR1FLAGSALTX SET) 
00003B ORG FDR1SPARE4 
000040 FDRIKEYPOS DS H PRIMARY KEY POSITION IN 
¥ DATA RECORD 
000042 FDRIKEYSIZE DS HL1 PRIMARY KEY LENGTH IN BYTES 
000043 FDR1HXBLK DS FL3 BLOCK-IN-FILE OF ROOT BLOCK 
* OF PRIMARY INDEX 
000046 FDRIDABLK DS FL3 BLOCK-IN-FILE OF STARTING 
* BLOCK OF AVAILABLE-BLOCK 
% CHAIN 
000049 FDR1PTRD DS FL3 FIRST DATA BLOCK IN FILE 
* 


(PRIMARY KEY SEQUENCE) 
PAA AAAI IAAI IAAI AOKI IAAI AAAI AHI OI IIASA IATA AAI IIR 


* FDR CHAIN - IN ALL FDR RECORDS: 
PIAA AAAI AAAI AAA AIA AAO AAI AI ATA A TATA AAAI OETA AH 


00004C FDR1CHAIN DS F (HL1,FL3) ADDRESS OF A FORMAT 2 FDR 
% FOR THIS FILE'S ADDITIONAL EXTENTS, 
* OR A FORMAT 3 FDR FOR THIS FILE'S 
ad ALTERNATE INDEXING DESCRIPTIONS, 
* OR BINARY ZEROES. THE ADDRESS IS 
* IN THE FORM: 
* (HL1) NUMBER STARTING FROM 0 
* OF FDR IN 1-PAGE BLOCK 
~ (FL3) BLOCK NUMBER IN VTOC FROM 0 
FDR1END EQU * 
FDR1LENGTH EQU FDRIEND-FDR1BEGIN 
FDRICNT EQU 25 # OF FDR1 RECORDS PER BLOCK 1% 
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FDR2 


000000 


000000 
000000 
000001 
000006 
OOOOOE 
000010 


000013 
000016 
00004C 


FDR2 
FDR2 DSECT 
. | 
* THE FORMAT 2 FILE DESCRIPTOR RECORD (FDR2) DESCRIBES UP TO 
* TEN (10) ADDITIONAL EXTENTS FOR A FILE (BEYOND THE FIRST 
* THREE). IT IS CHAINED FROM THE FILE'S FORMAT 1 FILE 
* DESCRIPTOR RECORD. A FORMAT 2 FDR MAY BE CHAINED TO ANOTHER 
* FORMAT 2 FDR. 
* 
* DATE 3/28/79 
% VERSION 4.00 
FDR2BEGIN DS OF FULLWORD ALIGNMENT 
FDR2FORMAT DS CL1 FORMAT (ASCII '2') 
FDR2SPARE1 DS CLS5 (UNUSED) 
FDR2FILENAME DS CL8 FILE NAME AS IN FORMAT 1 FDR 
FDR2SPARE2 DS CL2 (UNUSED) 
FDR2X4STRT DS FL3 EXTENT 4 (OR 14, 24, ETC.) 
* STARTING BLOCK ON VOLUME (FROM 0) 
FDR2X4END DS FL3 EXTENT 4 ENDING BLOCK ON VOL 
FDR2X5TOX13 DS 18FL3 EXTENT DEFINITIONS 5 TO 13 
FDR2CHAIN DS F (HL1,FL3) CHAIN TO NEXT FORMAT 2 FDR 
* FOR ADDITIONAL EXTENTS 
* (SEE FDR1CHAIN) 
FDR2END EQU * 
FDR2LENGTH EQU FDR2END-FDR2BEGIN 
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000000 


000000 
000000 


000001 
000000 
000004 
00000C 


000015. 


000014 


000018 
000019 


00001A 


00001B 


IORE 


IORE 

IORE DSECT 

* THE I/0 REQUEST ELEMENT (IORE) IS PASSED TO THE SYSTEM'S 

* START I/0 ROUTINE TO INITIATE AN OPERATION, IS QUEUED BY 

% THAT ROUTINE TO REPRESENT A REQUEST FOR PHYSICAL I/O SERVICE, 

* AND CONTAINS THE I/O STATUS WORD ON COMPLETION OF THE 

% REQUEST. IORES MUST BE RESIDENT IN THE SYSTEM 

* AREA. TASK CONTROL BLOCKS CONTAIN IORES FOR PAGING. 

* OFBS ADDRESS IORES FOR OTHER I/O. 

: ; 

* DATE 3/28/79 

* VERSION 4.00 

te 

IOREBEGIN DS OF 

IOREREQF DS BL1 REQUEST FLAGS 

IOREREQFNOUNFIX EQU X'80! SVC XIO DID NOT TEMPORARILY 

% FIX THIS PAGE, SO ISR MUST 

% NOT UNFIX IT 

IOREREQFPAGEIN EQU X'40' THIS IORE IS BEING USED 

* FOR DEMAND PAGEIN 

IOREREQFPAGEOUT EQU x'20' THIS IORE IS BEING USED 

* FOR DEMAND PAGEOUT 

IOREREQFIOACT EQU X'10' IORE ON PHYSICAL I/O 

* QUEUE 

IOREREQFNOCHK EQU x'08' XIO ISSUED; SUCCEEDING 

- CHECK NOT ISSUED 

IOREREQFHALTQ EQU X'04' "HALT I/O QUEUE' OPTION OF 

x XIO PASSED HERE TO ISR 

IOREREQFIVRQ EQU X'02' "INTERVENTION REQUIRED’ 

* INTERRUPT RECEIVED, BUT 

* NOT YET NOTICED BY CHECK SVC 

IOREREQFCIO EQU x'01' ISSUE CIO INSTRUCTION IF ON 

bi (ELSE ISSUE SIO INSTRUCTION) 
ORG IOREREQF 

IORECHN DS A CHAIN (FROM UCB) IN 3 LOW BY 

IOREIOSW DS CL8 I/O STATUS WORD SAVE AREA 

IOREIOCW DS CL9 I/O CONTROL WORD SUPPLIED BY 
ORG *-1 

IORESEMA DS A ADDRESS OF COMPLETION 

* SEMAPHORE 

* OR PAGING CODE 

* FIELDS PRESENT IN NON-PAGING IORES ONLY: 

e 

IOREIALCNT DS HL1 COUNT OF IAL SLOTS 

IOREIALUSED DS HL1 NUMBER OF IAL SLOTS USED BY 

¥ THIS IO OPERATION 

TORESCC DS HL1 SCAN CLASS FOR PAGE AFTER 

* "UNFIX' ON I/O COMPLETION 

ILOREWSLEVEL DS HL1 STORE AID CHARACTER ON THIS 


vs 


¥ 
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WORKSTATION LEVEL AFTER IO 
COMPLETION 


Q0001C IOREIAL DS OA INDIRECT ADDRESS LIST 
* IF IDA BIT IN COMMAND 
‘a (VARIABLE LENGTH) 
* 
* SPECIAL FIELDS FOR PAGING IORES (IN TCBS) ONLY: 
*« 
00001C ORG IOREIALCNT 
000018 IOREPGFLG DS BL1 PAGING FLAGS 
IOREPGFLGRECL EQU X'80' PAGE RECLAIMED DURING THIS 
* PAGEOUT IF SET ON PAGEOUT 
* COMPLETION (DEFERRED USE) 
000019 ORG IOREPGFLG 
000018 IOREPGTCB DS A ADDRESS OF ASSOCIATED TCB 
00001C IOREPGPAGENO DS BL1 PAGE NUMBER FOR REQUEST 
00001D IOREPGFLUB DS AL3 FLUB ADDRESS FOR REQUEST 
% 
IOREPGEND EQU * 
IOREPGLENGTH EQU IOREPGEND-IOREBEGIN 
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000000 OFB 


Feet He Ss H HH FS 


* 


000000 OFBBEGIN 


OFB 


OFB 
DSECT 


THE OPEN FILE BLOCK (OFB) IS CONSTRUCTED WHEN A FILE IS 
OPENED, AND CONTAINS INFORMATION FOR USE BY DATA MANAGEMENT 
AND 1/0 INITIATION ROUTINES WHICH MUST BE PROTECTED FROM 
USER PROGRAM MODIFICATION. ALL OPEN FILE BLOCKS ARE RESIDENT 
IN THE SYSTEM AREA. ALL OPEN FILE BLOCKS FOR A PARTICULAR 
DISK FILE POINT TO THE SAME FILE LOCATION AND USE BLOCK 
(FLUB). WHEN AN OFB IS CREATED, SPACE FOR AN IORE IS 
ALLOCATED AS WELL, AND THE IORE ADDRESS IS PLACED IN 
OFBIOREPTR. 


DS OD (DOUBLEWORD ALIGNMENT REQD) 
SAMPAIO AIIAIIIHIII 


KWINANA EIR EERE CA 


* BASIC SECTION: 
Ho KIKI REIRSON 


000000 OFBFLAGS DS OBLL FLAG BYTE 
* MODE FLAGS: 
OFBFLAGSWPSHARE EQU X'80' OPENED FOR WP SHARE MODE 1B*% 
OFBFLAGSOUT EQU x'40' OPENED FOR OUTPUT MODE 
OFBFLAGSIN EQU X'20' OPENED FOR INPUT MODE 
OFBFLAGSIO EQU X'10' OPENED FOR 10 MODE 
OFBFLAGSEXTEND EQU X'08' OPENED FOR EXTEND MODE 
OFBFLAGSSHARED EQU x'04' OPENED FOR SHARED MODE 
OFBFLAGSCPL2 EQU X'02' FOR USE BY LEVEL 2 COMMAND 
% PROCESSOR — LEVEL 1 MUST 
* NOT USE 
OFBFLAGSIPCB EQU X'OL' OPENED VIA "IPCB" 
000000 OFBUFB DS A UFB ADDR (USER FILE BLOCK) 
% (CONTAINS BINARY VALUE -1 IF 
¥ PRESUPPLIED OFB FOR 
% WORKSTATION USED BY COMMAND 
* PROCESSOR; CONTAINS 0 IF NO 
es UFB'S ARE CHAINED TO THE 
* OFB, OR IF THE OFB WAS 
* OPENED VIA "IPOPEN") 
000004 OFBUCB DS A UCB ADDRESS 
* (ZERO IF DUMMY) 
000008 OFBIOREPTR DS A IORE ADDRESS (FOR XIO SVC) 
00000C OFBTCB DS A ASSOCIATED TCB ADDRESS 
000010 OFBSEMA DS D (BL1,AL3,BL1,AL3) 
% 1/0 COMPLETION SEMAPHORE 
000018 OFBXIOCNT DS F NUMBER OF XIOS TO THIS 
* FILE SINCE OPENED 
00001C OFBTASKCHN DS A NEXT OFB THIS TASK OR ZERO 
000020 OFBLINKLEV DS HL1 LINK LEVEL ON WHICH 
% FILE WAS OPENED 
000021 OFBFLAG1 DS BLL FLAG1 BYTE 14 
OFBFLAG1LOCKED EQU X'80! FILE LOCKED 14 
OFBFLAG1CAN EQU X'O1' CLOSE ATTEMPTED BY CANCEL 14% 


* 
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OFB 


000022 


000024 
000024 
000028 


000028 
00002C 


00002C 


000030 
000024 


000028 


DS H #*% SPARE (MUST BE ZERO) 1A% 
+e 


OFBBASICEND EQU * END OF BASIC OFB BLOCK 


FC MII IRCA RRR TEIN TIAA ITB RIE THTET AE 


* DISK-ONLY SECTION (DEFINED IN OFBS FOR DISK FILES) 
te deteteteteletttte add AOA AIA AAAI AAR AIA IAI AAI 


ORG OFBBASICEND 
OFBFLUBPTR DS A ADDR OF FLUB FOR THIS FILE 
OFBCFLAGS DS OBL1 OFB SPECIAL CLOSE FLAGS 
OFBCFLAGSBYP EQU x'80' DENOTES DMS-CLOSE VECTOR 
ad SHOULD BE BYPASSED AT CLOSE 
* TIME DUE TO OPEN OR CLOSE 
Lg ERROR. (ALSO, NO LABEL 
¥ UPDATE DONE IF SET) 
OFBFILECHN DS A CHAIN OF OFBS THIS FILE 
* (HEAD IN FLUB) 
OFBBCOUNT DS OHL1 COUNT OF BUFFERS IN BUFFER 
* POOL IF PRESENT 
OFBBCT DS A BUFFER POOL CONTROL TABLE 
%« 


ADDRESS, IF ANY 
% teldckicickicitcitktincdcdccdntcHKiiciicniicciwiwkiiiicKenicicticiictcadictecteictictcKtickk 


* OFB "IPCB'" EXTENSION (DEFINED ONLY IF "OFBFLAGSIPCB" SET) 
te tdticicciciciicickickiciciieckiciicieicticiticiicciicinicdcectetciicsctcicictcttckseccn 


ORG OFBBASICEND 
OFBIPCB DS A ADDRESS OF THE “IPCB" 
* CONTROLLING THIS DEVICE 
DS 2A (RESERVED) 
 tedicictcictcicitickiciictciickiicnictickiciiiiciviKsthiciiceticsencictcscscictectcicricicnctctk 
OFBEND EQU * 
- OFBLENGTH EQU OFBEND-OFBBEGIN 
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000000 


000000 
000004 


000015 


00001B 


00001F 


000023 
000027 


000029 


00002F 
000035 


000036 


00003C 


000049 
00004C 


TPLAB 
TPLAB 


TPLABBEGIN 
TPLABID 
TPLABFILE 

* 

* 
TPLABVOL1SER 
“ 


* 

xc 
TPLABFILESECTION 
se 

% 

TPLABFILESEQ 

ve 


ve 


TPLABGENERATION 
* 

TPLABVERSION 

* 


TPLABCREATION 
* 


* 
* 
TPLABEXPIRATION 
* 


TPLABACCESS 
* 


TPLABBLKCOUNT 
* 


ve 

¥ 
TPLABSYSTEM 
te 
TPLABCREATOR 
TPLABSPARE1 
TPLABEND 
TPLABLENGTH 


DSECT 


DATE 3/28/79 
VERSION 4.00 


TPLAB 


MAGNETIC TAPE FILE HEADER, TRAILER, AND END OF VOLUME 
LABELS CONFORM TO ANSI STANDARDS, AND ARE AS DESCRIBED HERE: 
ONLY ID AND BLKCOUNT FIELDS ARE REQUIRED IN EOV1 AND EOF1. 


EQU * 


DS 
DS 


DS 


DS 


DS 


DS 


DS 


DS 


DS 


DS 


DS 


CL4 'HDR1', ‘EOV1', OR ‘EOF1' 

CL17 UP TO 17 ASCII CHARACTERS, 
LEFT ADJUSTED AND PADDED 
WITH BLANKS, NAMING THE FILE 

CL6 VOLUME SERIAL NUMBER MATCHIN 
‘VOLISER' IN VOLUME LABEL (OF THE 
FIRST VOLUME, IF A MULTI-VOLUME 
FILE) 

CL4'0001' ORDER OF VOLUME IN A MULTI- 
VOLUME FILE (ASCII '0001' FOR A 
SINGLE-VOLUME FILE) 

CL4 FILE SEQUENCE NUMBER 
ON MULTI-FILE VOLUME (1ST FILE 
IS ASCII '0001') 

CL4'0001' GENERATION NUMBER (CURRENTLY 
ALWAYS '0001', USE DEFERRED) 

CL2'00' VERSION IN GENERATION, 
CURRENTLY ALWAYS ZERO 

CL6 CREATION DATE IN THE FORM 
BYYDDD, WHERE B IS A BLANK, 

YY IS YEAR INTO CENTURY, 
DDD IS JULIAN DAY (001 TO 366) 

CL6 EXPIRATION DATE IN THE 
ABOVE FORMAT 

CLI’ ' ACCESS PROTECTION (FILE 
PROTECTION CLASS OR BLANK) 

CL6 BLOCK COUNT IN TRAILER LABEL 
AS SIX ASCII DIGITS. ALWAYS 
PLACED IN 'EOV1' AND '‘EOF1' 

LABELS. ASCII ZEROS IN HDR LABEL. 


DS CL13 CHARACTERS IDENTIFYING 
THE CREATING SYSTEM 

DS CL3 FILE CREATOR ID OR BLANKS 

DS CL4 RESERVED - MUST BE BLANKS 

EQU * 


EQU TPLABEND~TPLABBEGIN 
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IPLB2 


TPLB2 
000000 TPLB2 DSECT 
Po 
* MAGNETIC TAPE SECONDARY HEADER, TRAILER, AND END OF 
* VOLUME LABELS CONFORM TO ANSI STANDARDS, AS FOLLOWS: 
ve 
* DATE 3/28/79 
* VERSION 4.00 
¥* 
TPLB2BEGIN EQU * 
000000 TPLB2ID DS CL4 'HDR2', ‘'EOV2', OR ‘EOF2' 
000004 TPLB2RECFM DS CL1 'F' -— FIXED LENGTH RECORDS 
* 
* 'F' - FIXED LENGTH RECORDS 
* 'D' - VARIABLE LENGTH RECORDS 
* IBM FORMAT 
* 'w' - VARIABLE LENGTH RECORDS 
* WANG FORMAT 
* 'X' - VARIABLE LENGTH COMPRESSED 
* RECORDS WANG FORMAT 
* 'U' - UNDEFINED LENGTH RECORDS 
000005 TPLB2BLKL DS CL5 BLOCK LENGTH (ASCII) 
000004 TPLB2RECL DS CL5 RECORD LENGTH (ASCII) 
QOO00F TPLB20RG DS BL1 FILE ORGANIZATION 
TPLB20RGCONSEC EQU X'01' CONSECUTIVE 
TPLB20RGPRINT EQU x'40' PRINT FILE 
TPLB20RGPROG EQU x'80' PROGRAM FILE 
000010 TPLB2SPARE1 DS CL34 RESERVED FOR OPERATING 
% SYSTEM USE 
000032 TPLB2BOFF DS CL2 BUFFER OFFSET 
000034 TPLB2SPARE2 DS CL28 RESERVED - MUST BE ASCII BLA 
TPLB2END EQU * 
TPLB2LENGTH EQU TPLB2END-TPLB2BEGIN 
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000000 


000000 


000000 


000014 
000000 


UFB 


UFB 
UFB DSECT 
* 
THE USER FILE BLOCK (UFB) IS SUPPLIED IN THE USER'S 
MODIFIABLE AREA BY THE USER'S PROGRAM BEFORE OPENING 
A FILE, AND IS ADDRESSED TO REQUEST EACH OPERATION 
ON THAT FILE. THE ADDRESS OF THIS BLOCK IS PLACED 
IN THE OPEN FILE BLOCK BY ‘OPEN', AND THE ADDRESS OF 
THE OPEN FILE BLOCK IS PLACED IN THIS BLOCK. 


+e SF te HX 


DATE 1-9-81 
VERSION 5.4 


FBBEGIN DS OF (FULLWORD ALIGNMENT REQUIRED 
HUTTE EOE INTERBIKE ECLECTIC TCE TICE 
ACCESS METHOD SECTION 

* NO FIELDS NEED BE SUPPLIED BEFORE 'OPEN', BUT UFBERRAD 

* UFBEODAD, UFBRECAREA, AND UFBKEYAREA MAY BE PRESET 

* IF DESIRED. AFTER 'OPEN', THE USER'S PROGRAM NORMALLY 

* HAS OCCASION TO MODIFY ONLY THIS SECTION OF THE UFB. 

* THE FIRST BYTES OF EACH OF UFBVREAD, UFBVWRITE, UFBVREWRITE, 

UFBVDELETE AND UFBVSTART ARE ZEROED BY ‘OPEN‘ AND SET 

THEREAFTER TO FUNCTION MODIFIER VALUES BY THE USER'S PROGRAM. 

THE SUCCEEDING BYTES OF THESE FIELDS CONTAIN ADDRESSES 
SUPPLIED BY 'OPEN' WHICH SHOULD NOT BE ALTERED BY THE 

USER'S PROGRAM WHILE THE FILE IS OPEN. 

UFBFS1 AND UFBFS2 ARE SET TO X'30' BY ‘OPEN' AND MODIFIED 


+ %¢Q 4% £ + 


+ 


bg 


~*~ e+ & 


* THEREAFTER BY DATA MANAGEMENT FUNCTIONS. 
MRA IIIA AIEEE RICKI 
UFBVECT DS 5A BRANCH POINTS TO ACCESS 
* METHOD ROUTINES 
ve vedde deiek detckh foick Yeiele tetek tetek Kick detek diet devel Yodede delete etek Feiek 
* THE FOLLOWING FUNCTION MODIFIER VALUES ARE PLACED IN THE FIRST 
* BYTE OF THE WORD CONTAINING THE ADDRESS OF THE FUNCTION TO BE 
* PERFORMED FOR A USER PROGRAM BEFORE BRANCHING TO THE ROUTINE 
* ADDRESS. 

ORG UFBVECT 
UFBV DS OF (PREFIX TO EQUATE LABELS) 
* MODIFIERS FOR READ: 
UFBVHOLD EQU x'O1' (HOLD BLOCK EXCLUSIVELY) 
UFBVREL EQU x'04' (RELATIVE READ) 
UFBVKEYED EQU x'04' (KEYED READ) 
UFBVNODATA EQU X'08' (DO NOT MOVE DATA TO WORK 
* AREA ON READ) 
* MODIFIERS FOR READ OR REWRITE (WORKSTATION ONLY) : 
UFBVTABS EQU X'10' (READ OR REWRITE TABS — WS) 
* MODIFIERS FOR READ (WORKSTATION ONLY) : 
UFBVMOD EQU X'02' (READ MODIFIABLE - WS) 
UFBVALTR EQU x'40' (READ ALTERED — WS) 


* MODIFIERS FOR REWRITE (WORDSTATION ONLY) : 


UFBVSELW EQU X'40' (REWRITE SELECTED - WS) 
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UFB 


000000 
000000 
000004 
000008 
00000C 
000010 


000014 


000018 


* MODIFIERS FOR START (INPUT, I0, SHARED MODES; INDEXED DISK ONLY): 


(EQUAL TO) 
(GREATER THAN) 
(GREATER THAN OR EQUAL TO) 


* MODIFIER FOR START (SHARED MODE; IGNORED FOR INPUT & IO MODES) : 


(HOLD FILE) 

(RELEASE HELD FILE) 

(HOLD REQUEST FOR A RANGE) 
(HOLD CLASS IS RETRIEVAL) 
(LIST OPTION) 


* MODIFIERS FOR START (CONSECUTIVE OUTPUT & EXTEND MODES ONLY) : 


UFBVEQ EQU x'01' 
UFBVGT EQU x'02' 
UFBVGE EQU X'03' 
UFBVHFILE EQU x'80' 
UFBVRLS EQU x'20' 
UFBVRANGE EQU X'04' 
UFBVRETRIEVAL EQU x'40' 
UFBVLIST EQU X'10' 
UFBVINPUT EQU x'04' 
UFBVOUTPUT EQU x'08' 
UFBVEXTEND EQU x'20' 


(CHANGE TO TEMPORARY IO MODE 
(CHANGE TO OUTPUT MODE) 
(CHANGE TO EXTEND MODE) 


* MODIFIERS FOR START (CONSECUTIVE FILES WITH VARIABLE-LENGTH 


* RECORDS, INPUT AND I/O MODES ONLY): 


UFBVBEGIN 


UFBVSKIP 
“ 


* 


EQU x'10' 
EQU x'40' 


(BEGINNING OF FILE) 
(FROM CURRENT RECORD 
USING SIGNED WORD 
ADDRESSED BY KEYAREA) 


* MODIFIERS FOR START (PHYSICAL ACCESS METHOD ONLY) : 


UFBVCMD EQU X'80' 
UFBVWAIT EQU X'40' 
UFBVWAITS EQU x'41' 
UFBVWAITM EQU x'42! 
* 
te 
UFBVWAITA EQU x'43' 
ve 
UFBVHALTIO EQU X'20' 
%* MODIFIERS FOR START (WORKSTATION ONLY) : 
UFBVATINT EQU x'10' 
ve veteds devel dete dkiele dick Yolck fetede detedke detek 
ORG UFBVECT 
UFBVREAD DS A 
UFBVWRITE DS A 
UFBVREWRITE DS A 
UFBVDELETE DS A 
UFBVSTART DS A 


(***VAGUE NOTE?) 

(WAIT FOR I/O COMPLETION) 
WAIT FOR TC 1/0 COMPLETION 
ON THIS DEVICE ONLY 

WAIT FOR TC I/O COMPLETION 
ON ALL DEVICES OPENED BY 
THIS PROGRAM 

WAIT FOR TC I/O COMPLETIONS 
AND TC UNSOLICIT INTERRUPTS 
HALT TC IO OPERATION 


(TEST FOR ATTENTIONS RECEIVE 


dtek teiek Yetets teiele Teicve 


. FOR READ 

- FOR WRITE 

.- FOR REWRITE 
--FOR DELETE 

-- FOR START 


* THE FOLLOWING FOUR FIELDS MAY BE SET BEFORE 'OPEN' OR 
* BEFORE THE FIRST FUNCTION AFTER 'OPEN'. THEY MAY BE CHANGED 
* BY THE USER'S PROGRAM BEFORE ANY FUNCTION. IF UFBEODAD IS 0, 


** UFBERRAD WILL BE USED FOR END OF DATA AND INVALID-KEY CONDITIONS. 


* IF UFBERRAD IS 0, ABNORMAL TERMINATION WILL OCCUR ON ANY 
* ERROR (AND ON THE ABOVE CONDITIONS IF UFBEODAD IS 0 ALSO). 


UFBERRAD DS A I!O0 UNUSUAL CONDITION USER 
x ROUTINE ENTRY POINT, OR ZERO 
UFBEODAD DS A END OF DATA AND INVALID KEY 
¥ USER ROUTINE 

¥* ENTRY POINT, OR ZERO. 
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00001C 


000020 


000024 


000025 


UFBRECAREA DS A 

* 

UFBKEYAREA DS A 

¥ 

* 

* 

vs 

% 

UFBFS1 DS CL1 
UFBFS1SUCCESS EQU X'30' 
UFBFS1ATEND EQU X'31' 
UFBFSLINVKEY EQU X‘'32' 
UFBFS1IOERR EQU xX'33' 
UFBFS1ADMSERR EQU x'34' 
UFBFS1CANCEL EQU X'36' 
* 

¥ 

UFBFS1TIME EQU x'37' 
v 

UFBFS1SHARE EQU X'38' 
ve 

UFBFS1OTHER — EQU X'39' 
te 

UFBFS2 DS CLi1 
UFBFS2NOINFO EQU x'30' 
evs 

* THE FOLLOWING UFBFS2 VALUES ARE SET WITH 
UFBFS2SEQERR EQU xX'31' 
UFBFS2DUPKEY EQU x'32' 
UFBFS2NOREC EQU x'33' 
UFBFS2BYVIOL EQU X'34' 


UFB 


ADDRESS IN USER-MODIFIABLE S 


OF RECORD WORK AREA 


ADDRESS OF AREA CONTAINING 


SUPPLIED KEY OR RECORD NUMBER 

FOR START OR READ FUNCTIONS 

(IF ZERO FOR WORKSTATION FILES, 
LINE NUMBER (ROW) TAKEN FROM ORDER 


AREA) 


FILE STATUS BYTE 1 FOR DMS 
SUCCESSFUL COMPLETION 

AT END 

INVALID KEY OR RECORD NO. 
PERMANENT I/O ERROR 

ADMS FUNCTION ERROR 
CANCEL CODE STORED 


FOR UFBFINOMSG (OPEN,DMS,CLOSE) ; UFBFS2=C'0' 
MSGID AT UFBVREAD FOR O/C; NO MSGID IF DMS 


TIME-OUT CONDITION ON 
SHARED MODE RESOURCE WAIT 
FS FOR SHARER CONDITION 
RESOURCE WAIT 

OTHER CONDITIONS 


FILE STATUS BYTE 2 FOR DMS 


_NO FURTHER INFO 


UFBFSLINVKEY (X'32') 
SEQUENCE ERROR 
DUPLICATE KEY 

NO RECORD FOUND 
BOUNDARY VIOLATION 


* UFBFS2BDYVIOL IS ALSO USED WITH UFBFS1IOERR (FS = C'34') 


* THE FOLLOWING UFBFS2 VALUES ARE SET WITH UFBFS1LADMSERR (X'34') 


ATTEMPT TO UPDATE FILE 

WHILE NOT IN A TRANSACTION 
MCC ERROR 

ICK VIOLATION 

UNABLE TO LOG RECORD IMAGE 
INVALID VAB INFORMATION 

FILE PREVIOUSLY CRASHED 

ICK CHECK FAILED 

ADMS FILE WITH RECOVERY, 04% 


* HAS ALTERNATE INDEX WITH NO DUPS; USER MUST HOLD ENTIRE FILE TO 044 
* MAKE UPDATE, BUT DIDN'T HOLD WHOLE FILE. 04% 


* THE FOLLOWING UFBFS2 VALUES ARE SET WITH UFBS1SHARE (X'38') 


v4 
UFBFS2INTS EQU x‘31' 
* 
UFBFS2MCC EQU X'32' 
UFBFS2ICK EQU x‘'33' 
UFBFS2L0G EQU X'34' 
UFBFS2VAB EQU x‘'35' 
UFBFS2CRASH EQU X'36' 
UFBFS2DATA EQU X'37' 
UFBFS2UNQERR EQU X'38' 
* 
UFBFS2ACC EQU X'35' 
ve 
*& 
UFBFS2RESERR EQU X'36' 


deve 


UPDATE ACCESS DENIED FOR 
USER WITH READ-ONLY RIGHTS 
IN SHARED MODE 

RESOURCE CONTROL ERROR 


* THE FOLLOWING UFBFS2 VALUES ARE SET WITH UFBFS10THER (X'39') 


UFBFS2INVFUN 


rad 


EQU X'35' 


INVALID FUNCTION OR 


FUNCTION SEQUENCE 
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UFB 


000026 


000028 


UFBFS2INVCMD EQU x'36' 
¥ 

UFBFS2INVLTH EQU x'37° 
UFBFS2MASK EQU X'38' 
ve 

UFBFS2TRLERR EQU x'38' 
ke ; 

UFBFS2FMTERR EQU x'39! 


“ 


¥ 


Hoa? 
we 


INVALID COMMAND (ALIGNMENT 


OR ADDRESS ERROR FOR DIRECT 1/0) 


INVALID LENGTH 

INVALID ACCESS MASK 
(ALTERNATE INDEXED FILES) 
TRAILER COUNT NOT EQUAL 


TO BLOCKS READ (SET BY SVC 
CLOSE ONLY) 


FORMAT ERROR (BLOCK PREFIX, 


RECORD PREFIX,EXPANSION ERROR OR 
INVALID CHAIN FIELD) 


* NOTE: UFBFS2 CONTAINS THE TERMINATING ATTENTION CHARACTER (AID BYTE) 


* ON WORKSTATION READ SUCCESSFUL COMPLETION. 

eve 

* NOTE: THE FOLLOWING UFBFS2 VALUES ARE SET ONLY IF AN SVC OPEN 

* EXIT IS TAKEN. THESE VALUES ARE ALSO USED WHEN CREATING 

% THE OPEN EXIT MASK TO BE SUPPLIED TO THE OPEN SVC. 

UFBFS2XFILE EQU x'80' DUPLICATE FILE OR 

¥ FILE NOT FOUND 

UFBFS2XLIB EQU x'40' LIBRARY NOT FOUND 
UFBFS2XVOL EQU x'20' VOLUME NOT MOUNTED 
UFBFS2XSPACE EQU x'10' NO SPACE ON VOLUME 
UFBFS2XVTOC EQU x'08' NO VTOC SPACE ON VOLUME 
UFBFS2XTAPELD EQU x'08' WRONG TAPE LABEL/DENSITY 
UFBFS2XP0S EQU x'04' POSSESSION CONFLICT 
UFBFS2XPROT EQU x'02' PROTECTION CLASS VIOLATION 
UFBFS2XFORMAT EQU x'o1' OPEN FORMAT ERROR - ERROR 
* CLASS DESCRIBED IN UFBXCODE 
UFBAMEND EQU * 

UFBAMLENGTH EQU (UFBAMEND-UFBBEGIN) 


feat saleatoateat natant ontontoateateatoates? 


* FILE LOCATION AND ATTRIBUTE SECTION 


* ALL FIELDS IN THIS SECTION MUST BE SET (SOME OF THEM POSSIBLY 
* TO 'NULL' VALUES) BY THE USER'S PROGRAM BEFORE INITIALLY 

* ADDRESSING AN 'OPEN' TO THE UFB. 

* ALL RELEVANT FIELDS AND FLAGS SET NULL BEFORE 'OPEN' ARE SUPPLIED 
* HERE BY 'OPEN' PROCESSING AND MAY BE EXAMINED BY THE USER'S 

* PROGRAM. THE PROGRAM SHOULD NOT MODIFY THESE FIELDS BETWEEN 

* *CLOSE' AND A SUCCESSIVE 'OPEN' IF THE SAME FILE IS REQUIRED 


* (WITHOUT REPROMPTING) . 


4 tniciiidctit iii EIA I 

H MAGNETIC TAPE — MUST CONTAIN 
PHYSICAL BLOCK SIZE BEFORE OPEN 
IF OUTPUT MODE OR UNLABELLED 


UFBBLKSIZE DS 


¥* 


*“ 


" 
UFBRECSIZE DS 
* 


" 
n 
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TAPE. 


DISK OR DISKETTE — ALWAYS 2048 
AFTER OPEN EXCEPT WHEN USING 
PHYSICAL ACCESS METHOD (PAM) 


LOGICAL RECORD SIZE 


(MUST BE SUPPLIED BEFORE OPEN FOR 
OUTPUT OPEN MODE) 


00002A 


00002B 


00002C 


00002D 


00002E 


UFB 


FILE ORGANIZATION 
CONSECUTIVE 

INDEXED 

WORD PROCESSING FILE 

IBM VARIABLE-LENGTH RECORDS 
UNDEFINED RECORD FORMAT 
VARIABLE-LENGTH RECORDS 
PRINT FILE 

PROGRAM FILE 


OPTION FLAGS 
USE GETPARM = TYPE RD 
USE GETPARM = TYPE ID 


* UFBF1INOGET AMD UFBFINODISP USED BY SVC OPEN ONLY; NOT RESET BY DMS 


UFBFORG DS BL1 
UFBFORGCONSEC EQU X'01' 
UFBFORGINDEXED EQU x'02' 
UFBFORGWP EQU x'04' 
UFBFORGVIBM EQU X'08' 
UFBFORGU EQU x‘'10' 
UFBFORGVLEN EQU X‘20' 
UFBFORGPRINT EQU x'40' 
UFBFORGPROG EQU x'80' 
* 

UFBF1 DS BL1 
UFBF1NOGET EQU x'80' 
UFBF1NODISP EQU x'40' 
UFBF1PAM EQU X'20' 
UFBF1BAM EQU X'10' 
UFBF1PREVO EQU X'08' 
UFBF1WORK EQU x'04' 
ve 

+ 

UFBF1POOL EQU X‘'02' 
w 

* 

UFBF10OPEN EQU x‘O1' 
UFBF2 DS BLI1 
UFBF2ADMS EQU x'80' 
UFBF20UT EQU X‘40' 
UFBF2IN EQU x'20' 
UFBF210 EQU X'10' 
UFBF2EXTEND EQU x'08' 
UFBF2SHARED EQU X'04' 
UFBF2DALT EQU X'02' 
* 

UFBDEVCLASS DS BL1 
* 

UFBDEVCLASSWS EQU x'01' 
UFBDEVCLASSTAPE EQU X'02' 
UFBDEVCLASSDISK EQU x'03' 
UFBDEVCLASSPRT EQU X'04' 
UFBDEVCLASSTC EQU X'05' 
UFBDEVCLASSDUMM EQU X'FF' 
UFBFLAGS DS BL1 
UFBFLAGSUPDAT EQU X'80' 
UFBFLAGSCOMP EQU X'40' 
% wicictickk UFBFLAGSRECOV - RECOVERY=YES FOR 
UFBFLAGSRECOV EQU X'20' 
se 

UFBFLAGSALTX EQU x'10' 
UFBFLAGSLOG EQU x'08' 
UFBFLAGSALTP EQU Xx'08' 


PHYSICAL ACCESS METHOD 
BLOCK ACCESS METHOD 

THIS UFB PREVIOUSLY OPENED 
SCRATCH THIS WORK FILE ON 
CLOSE IF SET & FILE HAS A 
TEMPORARY NAME 

BUFFER POOLING FOR RAM 
(UFBBUFSTART MUST CONTAIN 
BCT ADDRESS AT OPEN TIME) 
THIS UFB OPEN IF SET 

OPEN MODE FLAGS 

TO OPEN IN ADMS MODE 

TO OPEN FOR OUTPUT MODE 

TO OPEN FOR INPUT MODE 

TO OPEN FOR IO MODE 

TO OPEN FOR EXTEND MODE 

TO OPEN FOR SHARED MODE 
DELETIONS IN PROGRESS 00% 
ON ALT-INDEX FILE 00% 
DEVICE CLASS (REQUIRED 

BY ‘OPEN') 

WORKSTATION 

MAGNETIC TAPE 

DISK 

PRINTER 

TC DEVICE 

DUMMY FILE 

FILE ATTRIBUTE FLAGS 

FILE HAS BEEN CLOSED 

DATA RECORDS IN COMPRESSED 
FORMAT 

BIT = ZERO FORMAT CH EC CCIE 


USE PREFORMAT AND RECOVERY 


PROCEDURES IF ZERO (INDEXED ONLY) 
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ALTERNATE INDICES IN FILE 
CONSEC LOG FILE FLAG 
ALTERNATE-TREE PROCESS FLAG 


UFB 


00002F 


000030 
000030 


000031 
000032 


00003A 


000040 


000048 


UFBFLAGSPART 


% + & 


% % 


UFBFLAGSADMS 
UFBFLAGSPRIV 
ke 


UFBDEVADDR 


+ 


+ S$ % 


UFBF3 
UFBPRTCLASS 
ke 
UFBFORMNO 
UFBPRNAME 


a9 
" 


UFBVOLSER 
% 


UFBFILENAME 


* 


% & 


% os 


6 


EQU X‘04' PARTIAL BACKUP FILE 


PROGRAM SETS BIT BEFORE OPEN OUTPUT 
(BAM OR PAM) TO SET BIT IN FILE 

LABEL, OR SETS BIT BEFORE NON-OUTPUT 
OPEN (BAM OR PAM) IF ABLE TO PROCESS 
PARTIAL FILES. INVALID FOR RAM. 


EQU X'02' ADMS DISK FILE INDICATOR 
EQU x‘01' _ PROGRAM FILE CARRIES 


DS 


DS 
DS 


DS 
DS 


DS 


DS 


DS 
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HL1 


ADDITIONAL ACCESS PRIVILIGES 
DEVICE ADDRESS (FOR PRINTERS 
AND WORKSTATIONS ONLY. 
USED IF SUPPLIED 
AND PLACED HERE BY 'OPEN' IF 
NOT SUPPLIED. HEX FF IF 
NOT SUPPLIED.) 


OBL1 (* NAME KEPT FOR COMPATIBILITY *) 


CL1 


HL1 
CL8 


CL6 


CL8& 


CL8 


PRINT CLASS (A-Z) 


PRINTER FORM NUMBER (BINARY) 
PARAMETER REFERENCE NAME 
(MUST ALWAYS BE SUPPLIED HERE 
FOR 'OPEN') 
VOLUME SERIAL NUMBER FOR 
VOLUME-ORIENTED FILES (TAPE 
OR DISK) 
(IF 6 ASCII BLANKS, TAKEN FROM 
PROCEDURE SPECIFICATION OR 
'OPEN'-TIME PROMPT. IF SPECIFIED 
IN NEITHER OF THESE WAYS, 
TAKEN FROM DEFAULT IN 
ETCB) 
DIRECTORY NAME (IF 8 ASCII 
BLANKS, DIRECTORY NAME TAKEN 
FROM PROCEDURE SPECIFICATION 
OR 'OPEN'-TIME PROMPT. 
IF SPECIFIED IN NEITHER PLACE 
AND VOLUME SERIAL ALSO 
OMITTED, DEFAULT IN ETCB 
USED) 


FILE NAME (UNDER DIRECTORY) 
(IF 8 BLANKS, FILE NAME TAKEN 
FROM PROCEDURE SPECIFICATION 
OR 'OPEN'-TIME PROMPT. 
WORK FILE SPECIFICATION IF 
ASCII '#' OR '$' FOLLOWED BY 
FOUR ALPHAMERICS - LAST 
3 CHARACTERS THEN MUST BE 
BLANKS - SEE WORK FILE 
DOCUMENTATION) 


000050 


000051 
000054 


000054 


000058 
000054 


000055 
000056 


000057 


000058 
000055 


000058 


UFBFPCLASS 


Ne 


% % 


a + + 


FBCREATOR 


FBALTCNT 


FBALTPTR 


+e ¢Q +Q + 


DS CL1 


DS CL3 


DS OBL1 


DS A 


UFB 


FILE PROTECTION CLASS 
VALUE TO LABEL IF OUT-MODE; 
TAKEN FROM USER 'SET' DEFAULTS IF 
X'00' IS SUPPLIED; 
VALUE FROM LABEL IF EXISTING FILE 
FILE CREATOR FOR NEW OR 
EXISTING DISK FILES 
COUNT OF ALTERNATE INDICES 
IN FILE AFTER SVC OPEN 
POINTER TO AXD1-AREA FOR DMS 
PROCESSING (ALL REFERENCE TO THE 
AXD1-AREA MUST USE UFBALTPTR) 


*- FOR DEVICES OTHER THAN DISK, THE ALTCNT FIELD IS FOR MICROCODE TYPE 
ORG UFBALTCNT 


UFBMCTYPE 


UFBMCTYPE27 80 
UFBMCTYPE3780 


UFBMCTYPETCD 


ry 


DS XLl DEVICE TYPE 
EQU x'O1' 2780 BATCH TC 
EQU X'02' 3780 BATCH TC 
EQU X'03' TC DIAGNOSTICS 


* FOR TC2780, TC3780 FILES, THE ALTPTR FIELD IS USED FOR THE TC 


* BATCH STREAM OPTIONS 


UFBTCDATAOPT 
UFBTCXMITOPT 


te 


UFBTCMAXRECSZ 


“ 


DS BL1 
DS BL1 


DS XL1 


TC STREAM DATA OPTION 

TC STREAM TRANSMIT/RECEIVE 
OPTION 

TC STREAM MAXIMUM RECSIZE 
MINUS 1 


* FOR WORD PROCESSING WORKSTATIONS, THE ALTPTR FIELD IS USED FOR 
* EXTENDED WS~ATTENTION INFORMATION 
ORG UFBALTPTR+1 


UFBWPAID 


vse 
UFBF4 
* 


UFBF4NOVTOC 
UFBF4RLSE 
* 


UFBF4BLKAL 
# 


% 


UFBF4VERIFY 
* 


UFBF4NOMSG 
* 

* 

% 
UFBF4NOACK 
v 

* 
UFBF4PMSG 
* 


ve 


DS XL3 EXTEND WS-ATIN INFORMATION 
DS BL1 ADDITIONAL DEVICE-DEPENDENT 
FLAGS 
EQU X'80' UNSTRUCTURED DISKETTE 
EQU X'40' RELEASE UNUSED SPACE 
ON CLOSE 
EQU X'20' ALLOCATE SPACE FOR NEW 
DISK FILE IN BLOCKS, 
FROM UFBNBLKS 
EQU x'10' VERIFY OPTION ON ALL 
DISK WRITES 
EQU x'08' NO RESPECIFY OR CANCEL 
MESSAGE FOR SVC OPEN 
ALSO NO CANCEL ON CLOSE; NO 
ACK/CANCEL FOR DMS. 
EQU x'04' NO EXCEPTIONAL CONDITION 
ACKNOWLEDGMENT MESSAGES 
FOR DMS FUNCTIONS 
EQU x'02' FOR INTERNAL USE BY DMS - 
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CLOSE SENDS MESSAGE TO 
UNSPOOLER IF SET 


UB 


000059 


00005C 


00005E 


000060 
000070 
000060 
000060 


000064 
' 000064 


000068 
00006A 
00006C 


OOOO6F 


000070 
000068 


00006C 


OOOO6F 


UFBF4ALLOWT 
% 


rd 
¥ 


UFBNRECS 
% 


ve 
¥ 


UFBLRECSAVE 
¥ 


UFBRETPD 

rd 

UFBLOCEND 
UFBLOCLENGCTH 


EQU Xx'01' USED BY SVC OPEN. PROGRAM 
SUPPLIES BIT=1 TO ALLOW DEV=TAPE. 
(OPEN SETS=1 IF UFBDEV=TAPE ALSO) 
OTHERWISE, DEV=TAPE NOT ACCEPTED. 


DS FL3 NUMBER OF DATA RECORDS IN 
FILE (EXAMINED BY 'OPEN' FOR 
OUTPUT OPEN MODE ONLY. 
EXCLUDES INDEX RECORDS, ETC) 

DS H RECSIZE SAVED HERE 
BY OPEN (BAM) 

DS H RETENTION PERIOD IN DAYS 
(MAXIMUM 999) 

EQU * 


EQU (UFBLOCEND-UFBBEGIN) 


PR ee ee ee 


* DATA MANAGEMENT SYSTEM SECTION 
He dededededede tiie A ITAA IRI IRA LITO, 


UFBBCB1 
* 


by 


UFBXIOFLAGS 
UFBXIOFLAGSRLS 
UFBOFB 
UFBBUFCMD 


UFBBUFADR 
* 


* 
¥ 
UFBBUFDATAL 


ve 


UFBBUFOFFSET 
* 


UFBBUFBLOCK 

% 

UFBBCBFLAGS 
UFBBCBFLAGSLOD 
UFBBCBFLAGSTOR 
UFBBCBFLAGSIO 
UFBBCBFLAGSPROT 
UFBBCBFLAGSEOB 


UFBBCBFLAGSEOF 
we 


* THE FOLLOWING FIELDS ARE 


* MODE ONLY. 


UFBTIMEEXIT 


% 
UFBHOLDID 
¥ 
UFBTIME 


devs 


DS BL16 BUFFER CONTROL BLOCK 
(CORRESPONDS TO SVC XIO PARAMETER 
LIST) 
ORG UFBBCB1 
DS OBLI1 FLAG BYTE FOR SVC XIO 
EQU x'80' RELEASE BUFFER AFTER WRITE 
DS A OFB ADDRESS 
DS OBL1 COMMAND BYTE FOR OPERATION 
DS A BUFFER MEMORY ADDRESS 
(BLOCK ADDRESS WITHIN 
BUFFER IF BUFFER LARGER 
THAN 2K) 
DS H LENGTH IN BYTES FOR 
OPERATION 
DS H OFFSET OF NEXT RECORD 
IN BUFFER 


DS FL3 (STARTING) BLOCK WITHIN 
FILE OF BUFFERED DATA 

DS BL1 FLAGS 

EQU x'01' BUFFER CONTENTS VALID 


EQU X'02' BUFFER TO BE REWRITTEN 

EQU x'04' BUFFER I/O IN PROGRESS 

EQU x'10' BUFFER IN PROTECTED MEMORY 
EQU X'20' END OF BLOCK REACHED 

EQU x'40' EOF BLOCK IN BUFFER 


USED FOR THE TIME-OUT OPTION IN SHARED 


ORG UFBBUFDATAL 
DS A EXIT ADDRESS FOR TIME-OUT 
RETURN (O = NO TIME-OUT) 


DS CL3 INITIALS OF HOLDER OF 
RESOURCE 
DS XL1 WAIT TIME IN SECOND 


(O = NO WAIT) 
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000070 
000072 


000074 
000077 
000074 
000077 
000074 


000077 
00007A 
000077 
00007A 
00007C 


00007A 
00007B 


00007C 


00007D 


00007E 
00007D 


UFB 


UFBBUFSIZE DS H BUFFER SIZE 

UFBCHKSIZE DS 4H RESIDUAL COUNT FROM XIO 
* (DMS USE ONLY) 

* UFBXDATE OR UFBOUTRECS IS AVAILBLE AFTER SVC OPEN AND BEFORE THE 
* FIRST DMS REQUEST; UFBRES3 IS AN INTERNAL DMS FIELD AFTERWARDS. 


UFBRES3 DS BL3 RESERVED FOR INTERNAL DMS 
ORG  UFBRES3 
UFBXDATE DS BL3 EXPIRATION DATE (EXIST FILE) 
ORG UFBRES3 
UFBOUTRECS DS FL3 NUMBER OF RECORDS REQUESTED 
* FOR OUTPUT MODE 
UFBNBLKS DS FL3 NUMBER OF 2048-BYTE BLOCKS 
¥ IN THE FILE 
ORG UFBNBLKS 
UFBDMSGID DS BL3 STORED MSG-ID(DMS NOMSG EXIT) 
UFBMAXTFR DS H MAXIMUM DATA TRANSFER IN 
* BYTES FOR DISK (SET BY OPEN) 
ORG UFBMAXTFR 
UFBRES1 DS BL1 FUTURE SPARE BYTE 
UFBOPFLAGS DS BL1 INTERNAL OPEN FLAGS 
UFBOPFLAGSPFA EQU x'80' PRINT-FILE ASSIGNMENT TO DISK 
UFBOPFLAGSPFS EQU x'40' PF - USER SUPPLIED FILE NAME 
UFBOPFLAGSWKA EQU X'20' WORK-FILE ASSIGNMENT BY OPEN 
UFBOPFLAGSPVS EQU x'10' PF - USER SUPPLIED VOLUME 
UFBOPFLAGSSCAN EQU x'08' IN SCAN BIT (WORK/SPOOL) 
Pied 
UFBLF DS BL1 LAST FUNCTION PERFORMED 
UFBLFOPEN EQU x'00' OPEN 
UFBLFREAD EQU x'04' READ 
UFBLFWRITE EQU x'08' WRITE 
UFBLFREWRITE EQU x'0C' REWRITE 
UFBLFDELETE EQU x'10' DELETE 
UFBLFSTART EQU x'14' START 
UFBLFCLOSE - EQU x'18' CLOSE 
FBLFMOD DS BL1 LAST FUNCTION MODIFIER 
* (DOESN'T CHANGE ON 'REWRITE') 
¥ (SEE UFBV ABOVE) 
ORG UFBLFMOD 
UFBXCODE DS BL1 EXTENDED OPEN EXIT CODE 
* UFBXCODE VALUES 1-8 SET FOR POSSESSION CONFLICT 
UFBXCODENOINFO EQU x'0O' NO FURTHER INFORMATION 
UFBXCODEUSE EQU x'01' DEVICE IN USE 
UFBXCODEDET EQU X'02' DEVICE DETACHED 
UFBXCODEVOLX EQU x'03' VOLUME EXCLUSIVE 
UFBXCODEPOSS EQU x‘04' FILE POSSESSION CONFLICT 
UFBXCODEPAGE EQU x'05' PAGING FILE - SYSTEM ONLY 
UFBXCODEIMAG EQU x'06' IMAGE FILE (INPUT MODE ONLY) 
UFBXCODEAOPEN EQU X'07' ALREADY OPEN - THIS USER 
UFBXCODEAUSE EQU x'08' ALREADY IN USE - THIS USER 
* 
* UFBXCODE VALUES X'10' - X'1F' SET FOR OPEN FORMAT ERROR 
UFBXCODETRACK EQU X'10' PROGRAM REQUIRES 7 TRACK 
* TAPE WHILE DRIVE IS 9 TRACK 


* 


OR VICE VERSA 
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UFB 


00007E 


000080 
000081 


000084 


000088 
00008A 
00008C 
00008A 
00008B 
00008C 
000084 


000088 


UFBXCODEDNPRT EQU X'11' UFB FORG=PRINT, WHILE LCK 
* FDR FORG NOT= PRINT LCK 
UFBXCODEDNPRG EQU x'12' UFB FORG=PROG, WHILE LCK 
* FDR FORG NOT= PROG LCK 
UFBXCODEDNCSC EQU X'13' UFB FORG=CONSEC, WHILE  LCK 
* FDR FORG NOT= CONSEC LCK 
UFBXCODEDNWP EQU x'14' UFB FORG=WP, WHILE LCK 
* FDR FORG NOT= WP LCK 
UFBXCODEDNINX EQU X'15' UFB FORG=INDEXED, WHILE LCK 
* FDR FORG NOT= INDEXED LCK 
UFBXCODEDFGR EQU x'16' UFB FORG NEITHER CONSEC LCK 
" NOR INDEXED--—-ERROR LCK 
UFBEREC DS H LAST RECORD NUMBER WITHIN 
* LAST BLOCK 
UFBVERSION DS HL1 UFB VERSION NUMBER *%%ricix% 
UFBEBLK DS FL3 LAST BLOCK NO. WITHIN FILE 
* FROM 0 
UFBBUFSTART DS A BUFFER MEMORY ADDRESS; 
sa BUFFER CONTROL TABLE 
* ADDRESS BEFORE 'OPEN'‘ 
* IF BUFFER POOLING 
* SPECIFIED (UFBF1POOL SET) 
UFBRDLTH DS H LENGTH IN BYTES OF 
* DATA IN BUFFER 
UFBPRTCOPIES DS H NUMBER OF PRINT COPIES 
* (FOR PRINTER FILES ONLY) 

ORG UFBPRTCOPIES 
UFBWPBLKSIZE DS xX WORD PROCESSING FILE CONTROL 
UFBWPBLS DS xX FIELDS, WP FILES BLKSIZE 
% AND BYTES IN LAST SECTOR 

ORG UFBBUFSTART 
UFBPTRB DS FL4 FIRST BLOCK IN INDEX 
* AREA OF PRIMARY EXTENT 
* (INDEXED FILES) 
UFBPTRC DS FL4 LAST BLOCK IN INDEX AREA 
* OF PRIMARY EXTENT 
* (INDEXED FILES) 
UFBDMSEND EQU * 
UFBDMSLENGTH EQU (UFBDMSEND-UFBBEGIN) 


HFM IAIII IITA UTTAR IOI ARIAT 


% 


% 


END OF UFB FOR ALL FILES/DEVICES EXCEPT T 
FILES AND ADMS(DATA AND RESTART) DISK FIL 


APE FILES, INDEXED DISK 
ES. 


WERE RARER ATO NEARER ARTE RRR EMBER EEC EEE MAME EET ATC 


INDEXED DISK FILE EXTENSION SECTION: 
UFBKEYPOS AND UFBKEYSIZE SHOULD BE FILLED 


IN BY THE PROGRAM BEFORE 


‘OPEN’ FOR A NEW INDEXED FILE (UFBF20UT AND UFBFORGINDEXED SET). 


THEY ARE SET BY 'OPEN' FOR AN EXISTING IN 
WILL SET UFBGKSIZE TO ZERO. THE USER'S PR 
BEFORE A ‘START’ FUNCTION. 'START' WILL Z 
USER'S PROGRAM MUST NOT MODIFY ANY OTHER 


** UFBGKSIZE IN THIS SECTION WHILE THE FILE 


DEXED FILE. ‘OPEN' 

OGRAM MAY SET IT NON-ZERO 
ERO IT AGAIN. THE 

FIELDS THAN 

IS OPEN. 


KittiiviiiinkiiccnicdcKkiiccKciccdvkicdcKKicidcicccwiccidcecciiciitdcddctecticks 
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00008C 
O0008E 
00008F 


000090 


000093 


000096 


000098 


00009C 


OOOO0A0 


OO00A4 


OOOOB4 


0000B6 


OOO0B8 
00008C 
000090 


OOO00A0 


OOO0A1 


UFB 


UFBKEYPOS DS H KEY POSITION IN LOGICAL RECO 


UFBKEYSIZE DS HL1 KEY SIZE IN BYTES 
UFBGKSIZE DS HL1 GENERIC KEY LENGTH OVERRIDE 
* MAY BE SET BEFORE ‘START’; 

= USED ONLY BY 'START' FUNCTION; 

* RESET TO BINARY O BY 'OPEN' AND 
¥ EVERY 'START' FUNCTION 

UFBHXBLK DS FL3 HIGHEST-LEVEL INDEX BLOCK 
* ADDRESS FOR KEYED ACCESS 
UFBDABLK DS FL3 FIRST DATA BLOCK ADDRESS 
* (CURRENTLY ALWAYS 0) 
UFBPKI DS H INDEX ITEMS PER BLOCK 

* FOR OUTPUT MODE 

UFBPTRD DS FL4& FIRST BLOCK BEYOND 

* PRIMARY EXTENT 

= (INDEXED FILES) 

UFBPTRI DS F NEXT AVAILABLE INDEX 

* BLOCK WITHIN PRIMARY EXTENT 

* INDEX AREA 

UFBPTRN DS F NEXT AVAILABLE INDEX 

¥ OR DATA BLOCK IN A SECONDARY 

* EXTENT (INITIALLY ZERO) 
UFBBCBIOUT DS BL16 BCB FOR INDEX CREATION, 
* OUTPUT MODE 

UFBPKD DS H RECORDS PER BLOCK FOR 
ba OUTPUT MODE 

UFBSPAREINX DS XL2 (RESERVED) 

UFBINXDISKEND EQU * 

UFBINXDISKLGTH EQU (UFBINXDISKEND-UFBBEGIN) 


HK WHER RAERARRERTTE IRENE TREE TREE EERE EERIE 


* MAGNETIC TAPE FILE EXTENSION SECTION: 
* FIELDS UFBTLABELS, UFBTDEN, UFBTSEQ AND UFBTFLAGS MAY BE SET 
* BEFORE 'OPEN' TO REQUEST OUTPUT LABELING OPTIONS, DENSITY 
* AND FILE POSITIONING. 
* ALL RELEVANT FIELDS AND FLAGS NOT SET BEFORE ‘OPEN' ARE SUPPLIED 
* HERE BY 'OPEN' PROCESSING AND MAY BE EXAMINED BY THE USER'S 
* PROGRAM. 
KO IRCA AAR ITINERARIES TINA INNER 
ORG UFBDMSEND 


UFBTSPARE1 DS BL4 (RESERVED) 

UFBTBCB DS BL16 ADDITIONAL BUFFER CONTROL 
* BLOCK FOR TAPE DOUBLE 

* BUFFERING 

UFBTLABELS DS BL1 REQUESTED LABELING (OUTPUT) 
% OR LABEL TYPE ON TAPE 

* (INPUT) 

UFBTLABELSNL EQU X'01' UNLABELLED 

UFBTLABELSANY EQU X'02' ANY TYPE OF LABEL 
UFBTLABELSAL EQU X'04' ASCII LABELS 

UFBTLABELSIL EQU x‘'08' IBM LABELS 

UFBTDEN DS BL1 TAPE DENSITY 

UFBTDEN800 EQU X'01' 800 BPI 

UFBTDEN1 600 EQU x'02' 1600 BPI 


a7 37 


UFB 


0000A2 


OO000A4 


0000A5 
0000A6 


OOOOAC 


OOO0AD 


OOOOB8 


0000B8 


OOOOBC 
OOOOBE 
0000C0O 
0000C2 
0000C4 


0000C4 


UFBTDEN556 
UFBTSEQ 
" 


¥ 
% 


UFBTFLG 
UFBTFLGALLOWNL 
UFBTFLGSWITCH 


ras 


UFBTFLGEODEOV 
* 


UFBTFLG7TRACK 
* 


UFBTFLGNOHDR2 


UFBIVOLSEQ 
ve 


ad 

UFBTSAVEVOL 
* 

ve 

UFBTPARITY 

* 
UFBTPARITYODD 
UFBTPARITYEVEN 
UFBTSPARE2 
UFBTAPEEND 
UFBTAPELGTH 


UFBADMSFLG 

UFBADMSFLGRS 
UFBADMSFLGBI 
UFBADMSFLGAI 


UFBADMSFLGCRASH 


ve 


UFBADMSFLGCUPD 


¥ 


UFBADMSFLGEXTCK 


* 
UFBMCCPTR 
ve 

UFBMCC# 
UFBSCHEMAID 
UFBVIEWID 
UFBRECORDID 
UFBADMSLOG 


*“ 


UFBADMSSPB 


ra 


to 


EQU x'03' 
DS H 


DS BLI 
EQU X'80' 
EQU x'40' 
EQU X'20! 
EQU X'10' 
EQU X'08' 
DS BL1 

DS CL6 


DS BL1 


EQU X'O1' 
EQU X'02' 
DS BL11 
EQU * 


556 BPI 024 
TAPE FILE SEQUENCE NUMBER 
(SET BEFORE OR DURING 

OPEN TO REQUEST POSITIONING 
AND AVAILABLE AFTER OPEN) 
TAPE-RELATED FLAGS 

wie OBSOLETE **«* 

TAPE VOLUME SWITCH REOPEN 
IN PROGRESS 

TAKE EOV1 TRAILER LABEL AS 


EOF1 LABEL 

USE 7 TRACK TAPE DRIVE FOR 
THIS FILE 

NO HDR2 FILE LABEL 01% 


TAPE VOLUME SEQUENCE NUMBER 
(ORDER OF VOLUME IN A 
MULTIPLE VOLUME FILE) 
VOLUME NAME OF FIRST 
VOLUME OF A MULTI-VOLUME 
FILE SAVED HERE 

TAPE PARITY (7 TRACK TAPE 
ONLY) 

ODD PARITY 

EVEN PARITY 

(RESERVED - MUST BE 0) 


EQU (UFBTAPEEND-UFBBEGIN) 
% tetcteicckicihickictidcdcdddddeocddcactiiicdcleckiviteicdcicciccddcciedivkiciictitictciccitdetick 


* ADMS DISK FILE EXTENSION SECTION: 
Ke deiciiktciiciii td AT OA AI AAI AAA AAI 


DS OBL1 
EQU X'80' 
EQU x'40! 
EQU X'20' 
EQU X'10! 


EQU X'08' 
EQU X'04' 
DS A 

DS XL2 
DS XL2 
DS XL2 
DS XL2 
DS OXL1 


DS A 
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ADMS FLAG 

RESTART FILE 

KEEP BEFORE IMAGE 

KEEP AFTER IMAGE 

SOFT OR HARD CRASH OCCURED 
ON THIS FILE 

INDICATE CONSECUTIVE FILE 


SIZE CHANGED 
INDICATES FIRST WRITE 03% 
TO EXTENDED FILE 034 


POINTER TO MCC CONTROL 
BLOCK (MAP—CONVERS ION-CHECK) 
## OF MCC ENTRIES 

SCHEMA ID 

VIEW ID 

RECORD TYPE ID 

RECORD IMAGE LOG TYPE ON 
THE AUDIT TRAIL FILE 
RESERVED USE BY SHARING 
TASK ONLY. ADDRESS OF THE 
SHARED FILE POSITION BLOCK 
(SPB) OF THIS USER/FILE 


0000C8 


0000CC 
0000B8 


0000B9 
OOOOBA 
OOOOBC 
0000C4 


UFB 


UFBADMSREC DS A ADDRESS OF THE DEFAULT 
* RECORD FOR THIS SCHEMA 
UFBADMSEND EQU * 

UFBADMSLGTH EQU (*-UFBBEGIN) 


He detetetctetctetetesctehhe tells RS AAI AIASIC IAAT IACI TCC LOTTA 


* RESTART DISK FILE EXTENSION SECTION: 
He delete htt IIIA AIA AIA IAI AIA AAAI AAAI ASAT IAAIAAAIOI I 


ORG UFBADMSFLG 
DS  XL1 

UFBADMSFLGND EQU x'40' RESTART FILE EMPTY 
UFBADMSFLGNEXT EQU X'20' RESTART FILE READ NEXT 
UFBADMSFLGPRIOT EQU X'10' RESTART FILE READ PRIOR 
UFBRSUSCNT DS XL1 COUNT OF RESTART USER 
UFBRSCURR DS XL2 RESTART CURRENCY POINTER 05% 
UFBRSFILENAME DS CL8 PSEUDO-RESTART FILE NAME 
UFBRSSPAR2 DS BL8& (RESERVED) 
UFBRSEND EQU * 
UFBRSLGIH EQU (*-UFBBEGIN) 
UFBEND EQU * 
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VOL1 


000000 


000000 
000004 
00000A 


00000B 
000025 


000028 
000025 


000033 
00004F 
000050 
000058 


00005B 


O0005E 


000061 


000064 


000067 


00006A 


00006D 
OOOO6F 
000070 
000072 
000074 
000076 
000078 


VOL1 
VOL1 DSECT 
% THE VOL1 RECORD IS THE STANDARD VOLUME LABEL FOR DISK OR 
* MAGNETIC TAPE. ALL FIELDS ARE IN ASCII CHARACTERS.EXCEPT THE 
* FDIR EXTENTS AND CREATION DATE. THIS RECORD ON DISK IS AT 
* ADDRESS F'1', FOLLOWING THE IPL TEXT RECORD. 
¥ 
* DATE 11-12-74 
* VERSION 1.01 
* 
VOL1BEGIN EQU * 
VOLLID DS CL4'VOL1' CHARACTERS 'VOL1' 
VOL1SER DS CL6 VOLUME SERIAL NUMBER 
VOL1ACCESS DS:.C"-? FILE PROTECTION CLASS 
* OR BLANK 
VOL1RESRV1 DS BL26 RESERVED - ASCII BLANKS 
VOL1CREATOR DS CL3 FILE CREATOR ID OR BLANKS 
= FOR MAGNETIC TAPE ONLY 

ORG VOL1CREATOR 

VOL1OWNER DS CL14 OWNER ID (OPTIONAL) 
¥ FOR DISK AND TAPE VOLUMES 
VOL1RESRV2 DS BL28 RESERVED - ASCII BLANKS 
VOL1LEVEL DS CL1'1' MUST BE AN ASCII ‘'1" FOR TAP 
VOL1TAPEEND EQU * 
VOL1TAPELENGTH EQU VOL1TAPEEND-VOL1BEGIN 
VOL1SYSTEM DS CL8 SYSTEM IDENTIFICATION 
VOL1CREDATE DS PL3 VOLUME INITIALIZATION DATE 
* (PACKED YYDDD+) 
VOL1X1STRT DS FL3 VOLUME TABLE OF CONTENTS 1ST 
* EXTENT STARTING BLOCK ON 
* VOLUME FROM 0 
VOL1X1END DS FL3 FDIR 1ST EXTENT ENDING BLOCK 
* PLUS 1 
VOL1X2STRT DS FL3 VOLUME TABLE OF CONTENTS 2ND 
* EXTENT STARTING BLOCK ON 
* VOLUME FROM 0 
VOL1X2END DS FL3 FDIR 2ND EXTENT ENDING BLOCK 
* PLUS 1 
VOL1X3STRT DS FL3 VOLUME TABLE OF CONTENTS 3RD 
* EXTENT STARTING BLOCK ON 
* VOLUME FROM 0 
VOL1X3END DS FL3 FDIR 3RD EXTENT ENDING BLOCK 
* PLUS 1 
* (EXTENTS 2 AND 3 RESERVED. X2STRT THOUGH X3END MUST CONTAIN 
* BINARY ZEROES.) 
VOL1RESRV3 DS BL2 RESV'D IN DISK VOL1 LABEL 0% 
VOLIUCBTYPE DS ALI UCB TYPE Or 
VOL1VCBBC DS AL2 BLOCKS PER CYLINDER O* 
VOL1VCBMAXTFR DS AL2 MAX TRANSFER (BYTES) O* 
VOL1VCBCV DS AL2 CYLINDERS PER VOLUME O* 
VOL1VCBCVP DS AL2 CYLINDERS PER PHYS VOLUME 0% 
VOL1RESRV4 DS BL136 RESV'D IN DISK VOL1 LABEL 04 
* ASCII BLANKS 
VOL1DISKEND EQU * 
VOL1LENGTH EQU 256 
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CHAPTER 6: SUPERVISOR CALLS 


6.1 INTRODUCTION 


This chapter describes the input parameters, outputs, and 
function of each supervisor call (SVC) which is directly 
accessible to normal user programs. SVC descriptions are ordered 
by SVC number, beginning with SVC 0. The following list is a 
summary of all available SVC's. Those with names in parentheses 
are normally not accessible to user programs and so are not 
described in this manual. 


Name Number Residency Inner SVC Only 
OPEN svc 0 (NR) 

CLOSE sve 1 (NR) 

TIME svc 2 (NR) 

XIO svc 3 (R) 

LINK SVC 4 (NR) 

GETBUF svc 5 (NR) 

FREEBUF SVC 6 (NR) 

(WAIT) svc 7 (R) I 
(SEND) svc 8 (R) I 
(FIX/UNFIX) svc 9 (NR) I 
(GETMEM) svc 10 (R) I 
(FREEMEM) svc 11 (R) I 
HALTIO SVC 12 (NR) 

(DTI) svc 13 (R) 

ALEX SVC 14 (NR) 

UNLINK svc 15 (NR) 

CANCEL SVC 16 (NR) 

CHECK SVC 17 (R/NR) * 

(SEIZE/RELEASE) SVC 18 (R) I 


* ‘Intervention required' handling and 1/0 error logging 
facilities of CHECK may be non-resident. 
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READVTOC Svc 19 (NR) 


GETPARM SVC 20 (NR) 

(GETDISK) SVC 21 (NR) I 
(FREEDISK) SVC 22 (NR) I 
(CREATFDR) SVC 23 (NR) I 
READFDR SVC 24 (NR) | 
(UPDATFDR) SVC 25 (NR) I 
RENAME SVC 26 (NR) 

SCRATCH SVC 27 (NR) 

EXTRACT SVC 28 (NR) 

(PLEASE) Svc 29 (NR) 

MOUNT SVC 30 (NR) 

PCEXIT SVC 31 (NR) 

SETIME/RESETIME SVC 32 (NR) 

PUTPARM svc 33 (NR) 

(MWAIT) SVC 34 (R) I 
SET Svc 35 (NR) 

XMIT SVC 36 (R) 

CREATE Svc 37 (NR) 

DESTROY SVC 38 (NR) 

CEXIT SVC 39 (NR) 

GETDIAG/FREEDIAG SVC 40 (NR) 

DISMOUNT SVC 41 (NR) 

PROTECT Svc 42 (NR) 

LOGOFF SVC 43 (NR) 

reserved SVC 44 

(LOADCODE) Svc 45 (NR) 


Where input parameters to an SVC routine are supplied on the 
stack, they are removed before returning to the issuer, leaving 
only the specified output values. 
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Open File 


OPEN 


Inputs: 


Outputs: 


(SVC 0) NON-RESIDENT 


The top word of the stack addresses a User File Block 
(UFB) containing: 
Reference name (UFBPRNAME) 
Optional parameter indicators (UFBF1) 
Mode flags (UFBF2) 
Device class (UFBDEVCLASS) 
Device dependent flags (UFBF4) 
A new workstation file or printer file must contain: 
File organization (UFBFORG) 
Logical record size (UFBRECSIZE) 
A new indexed disk file must contain: 
Key position (UFBKEYPOS) 
Key size (UFBKEYSIZE) 
A new magnetic tape file must contain: 
Physical block size (UFBBLKSIZE) 
Tape sequence number (UTBTSEQ) 
And a new disk file must contain: 
Disk space requirement UFBNRECS 
A new or existing file may optionally contain: 
Complete actual file name and volume 
(UFBVOLSER , UFBDIRNAME ,UFBFILENAME) , or device 
number, or unqualified name of member’ within 
library or volume (UFBFILENAME). For an existing 
tape or disk file, if UFBFORG or UFBRECSIZE are 
supplied, they must agree with the values in the 
file label. Also, for tape files, either filename 
must be supplied or UFBTSEQ must be non-zero. For 
disk files, UFBBUFSIZE may be supplied as_ the 
maximum buffer size required. 
Fields which may be preset, but are not used during 
‘OPEN' (except for TC files): 
UFBERRAD, UFBEODAD, UFBRECAREA, UFBKEYAREA. 
For TC files, UTBRECAREA contains the address of the TC 
connection parameters. 


The high-order byte of the top word of the stack may be 
set for the OPEN exit option as described below. 


Open File Block (OFB) created in protected memory. 
Device indication placed in OFB (OFBUCB). Mode flags 
copied to OFB from UFB (UFBF2). File Location and Use 
Block (FLUB) created for disk file if not already 
present (for another task). Extent information placed 
in FLUB for disk files. Length of extent list placed 
in FLUB for disk files. File Descriptor Record (FDR1) 
block and record numbers placed in FLUB for disk 
files. Sharing mode flags set in FLUB. 


OPEN (SVC 0) 


Addresses of I/O function processing routines placed in 
UFBVREAD through UFBVSTART. Number of records in file 
' placed in UFBNRECS for disk files or for magnetic tape 
files opened in EXTEND mode. Sequential record pointer 
initialized to first record of file (last record of 
file plus one record if EXTEND mode). Buffer addresses 
and lengths placed in buffer control fields of UFB 
(UFBBUFADR, UFBBUFSIZE), and these buffers marked 
"contents not valid' (in UCBBCBFLAGS) and ‘buffer in 
protected memory' when required. The file status bytes 
(UFBFS1, UFBFS2) are set = '00'; UFBLF is set = Open. 


For existing files only: 
File organization indicated (UFBFORG) 
Logical record size supplied (UFBRECSIZE) 
Block size supplied (UFBBLKSIZE) 
For disk files only: 
File attribute flags indicated (UFBFLAGS) 
Record size from label supplied (UFBLRECSAVE) 
Last block number in file supplied (UFBEBLK) 
Last record number in this block supplied (UFBEREC) 
Number of 2K blocks within file extents supplied 


(UFBNBCKS) 
For indexed disk files only: 
First data block number (relative - within file) 
supplied (UFBDABLK) . 
Highest-level index block number (relative - within 


file) supplied (UFBHXBLK) 

For existing indexed disk files only: 
Key position supplied (UFBKEY?POS) 
Key size supplied (UFBKEYSIZE) 


The Volume Control Block (VCB) for a volume containing a 
disk file is updated to indicate that an additional file 
is open on this volume (VCBOCNT). 


For disk or tape files, buffers are allocated from the 
user-modifiable segment and their allocation recorded in 
the task's extended Task Control Block. For disk or 
tape files, no buffers are allocated when physical 
access method functions are used (UFBF1PAM set). 


Program-supplied file, volume, and device information 
(as supplied through the ‘Open Parameters’ sections of 
the UFB) remains in the UFB, or is replaced with 
information acquired by OPEN through GETPARM. 


For device = dummy, an OFB is set up to indicate that a 
null file has been opened. There is no IORE, and 
OFBIOREPTR and OFBUCB are zero. A null file is valid in 
INPUT mode only and all DMS read requests to the file 
return with file-status='10' (end-of-file). UFBRECSIZE 
and UFBFORG are not set by OPEN for a null file. 
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OPEN (SVC 0) 


For device = disk and UFBF4NOVIOC set, a disk volume 
without a Volume Table of Contents (VTOC) is indicated. 
In this case, the unique filename in the FLUB is created 


by setting FLUBFILENAM1 and FLUBFILENAM2 = blanks; 
FLUBFDRR and FLUBFDRB are zer6; and the volume (through 
FLUBVCB) will have VCBFLAGSNOVTOC set. The FLUB 


contains one extent which allows access to all blocks on 
the volume. For NOVTOC, the file organization is 
consecutive and the record size is 2K unless the user 
program supplies a record-size. Extend and Shared Modes 
are not supported for NOVTOC volumes. 


For output mode, UFBF4RLSE is set. This setting may be 
overridden by the user when the OPEN-GETPARM is issued 
or the bit may be cleared by the program after OPEN. 
The bit causes unused space in the file to be released 
by CLOSE. 


The OPEN exit option is available by setting the high- 
order byte of the top word of the stack. This byte can 
indicate the conditions listed below. If a condition 
arises for which the corresponding bit is set, then 
control returns to the program at the next instruction 
in sequence, rather than SVC OPEN issuing a GETPARM 
(RESPECIFY). If the exit is taken, UFBFS1 = X'39', 
UFBFS2 = a mask for the appropriate condition; and 
UFBPREVO is set. The SVC OPEN may be reissued after an 


- OPEN exit has been taken. 


OPEN exit conditions: 


UFBFS2XFILE (X'80') - Return if the file is not found 
(non-OUTPUT) or if a duplicate 
file name is found (OUTPUT 


mode). 

UFBFS2XLIB (X'40') - Return if the library is not 
found (non-OUTPUT mode). 

UFBFS2XVOL (X'20') - Return if the volume is not 
mounted. 

UFBFS2XSPACE (X'10') - Return if there is insufficient 


space on the volume for a new 
file (OUTPUT mode). 


OPEN (SVC 0) 


UFBFS2XVTOC (X'08') - Return if there is no VIOC space 
on the volume (OUTPUT mode). 


UFBS2XTAPELD (X'08') - Return tape label type or tape 
density is not acceptable to 
the program. 


UFBFS2XPOS (X'04') - Return for possession  con- 
flict, which includes file 
already open by current pro- 
gram, file opened by other 
program and open modes  con- 
flict and volume possession is 
exclusive for another user. 


UFBFS2XPROT (X'02') - Return if the user does not 
have access rights required to 
open the file. 


UFBFS2XFORMAT (X'01') - Return if there is an error in 
specification of file format. 
Error class is described in 
UFBXCODE. 


A NO-MESSAGE option is also available such that control 
will return to the program (at the next instruction in 
sequence) whenever any condition arises for which a 
RESPECIFY (or CANCEL) message would normally be returned. 

If UFBF4NOMSG is set, then the MSG-ID (4 bytes) of any 
RESPECIFY or CANCEL message is stored in the first 4 
bytes of the UFB and UFBFS1=X'36' and UFBFS2=X'0'. The 
NO-MESSAGE option is checked after any open-exit checking 
is performed. (Open-exits provide a more exact 
indication of the problem; the NO-MESSAGE option is 
useful for tasks with special processing requirements.) 


Note 1: This list of indirect outputs of ‘OPEN', 
although extensive, is not intended to be 
completely exhaustive. 


Note 2: When creating an indexed file in OUTPUT mode, 
the ‘packing density’ for both index blocks and 
data blocks may be set by the user. For exam- 
ple, if 20 records at 100 bytes each would nor- 
mally fit into a data block, then at 80 percent 
packing, each data block would be loaded with 
only 16 records. UFBPKD (data) and UFBPKI 
(index) are settable by the user before Open; 
OPEN will use the binary value as a percent- 
age. A value of 50-100 will be accepted as the 
percentage value for packing. Any value 
outside this range will be ignored; the default 
used will produce full packing. UFBPKD and 
UFBPKI should not be modified after OPEN. 
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Function: 


OPEN (SVC 0) 


Note 3: For OUTPUT MODE DISK FILES, UFBOUTRECS 
contains the record count used when allocating 
file space. This value is available immedi-~ 
ately after SVC OPEN. UFBNRECS=0 after OPEN. 


Note 4: A complete description of Work files and Print 
files (including SVC OPEN processing) is 
included in Chapter 2 of this document. 


Prepares a file for processing by Data Management 
System functions. Information from the file label is 
brought into memory. Devices and volumes are allocated 
and reserved as required. Control blocks are set up. 
Buffer space is allocated. The OPEN function may 
interface with a conversational user's workstation to 
request information which has not been supplied. 


6-7 


Close File 


CLOSE 


Inputs: 


Outputs: 


(SVC 1) NON-RESIDENT 


The top word of the stack addresses (open) User File 
Block (UFB). The high-order byte of this word may have 
the following flag bits set: 


Bit 0=1 Force end-of-volume REEL. 
Bit 1 =1 No rewind (magnetic tape). 
Bit 2=1 Rewind and unload (magnetic tape). 


The other bits of this byte must be zeroed. 


Open File Block (OFB) in protected area is deallocated, 
and unchained from the task's TCB (OFBTASKCHN) and _ the 
FLUB for the file (OFBFILECHN). File Location and Use 
Block (FLUB) in protected area is deallocated if the 
file is no longer open to any task. 


Volume Control Block (VCB) for volume containing disk 
file is updated to indicate that the file has _ been 
closed (VCBOCNT). Unit Control Block (UCB) for 
nonshared devices marked 'deallocated'. 


Any records which remain to be written from buffers are 
written (as specified by UFB buffer control fields), 
and then these buffers are deallocated and marked as 
such in the Task Control Block (TCBAVBUF). 


For a TC file, a DISCONNECT operation is performed for 
the associated line if no other files remain open which 
are associated with that line. 


For disk and tape files, the file label is rewritten if 
the file was being processed in 10, SHARED, OUTPUT or 
EXTEND modes (FDR1 for disk, trailer labels for tape). 
The updated number of records in the file is placed in 
this label (from UFBNRECS or as calculated from UFBEBLK 
and UFBBUFOFFSET) . 


For OUTPUT mode (consecutive files only), unused. blocks 
in the file are released when UFBF4RLSE is set. 


For disk files, these additional label fields are 
updated when required: 
Date of last modification (FDRIMODDATE) 
Last record's block within file (FDR1EBLK) 
Last record's number in block (FDRIEREC) 
Highest-level index block number (FDRLHXBLK) 
First data block number (FDR1DABLK) 
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CLOSE (SVC 1) 


Function: Removes a file from processable status. Information 
remaining in memory is written to the secondary storage 
device containing the file or discarded. Memory areas 
allocated for processing this file are released and may 
be used for other purposes. The User File Block (UFB) 
is returned to a state in which another OPEN can be 
issued on the file. The file status reflects the last 


operation performed on the file by Close (if any) or by 
DMS. 
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Get Date and Time 


TIME 


Inputs: 


Outputs: 


(SVC 2) NON-RESIDENT 


The top word of the stack contains a binary 0 if the 
time is to be returned in hours, minutes, seconds, and 
hundredths of seconds (packed decimal), or a binary 1 if 
the time is to be returned in hundredths of seconds 
(from midnight) binary. 


The next word contains a binary 0 if the Julian day is 
to be returned, or a binary 1 if the date as 
year-month-day is to be returned. 


Time returned in the top word of the stack as either: 

(a) Packed decimal '‘HHMMSSth' where HH is hour (on 
24-hour clock), MM is minute-in-hour, SS _ is 
second-in-minute, t is. tenth of second andh is 


hundredth of second, or 


(b) Binary hundredths of second from preceding midnight. 


' Date returned in the next word as packed digits in one 


Function: 


of these formats: 


(a) '00 YY DD DF', where YY is year-in-century, DDD is 
day-in-year, F is hexadecimal 'F' for unpacking. 


(b) 'OY YM MD DF’, where YY is year-in-century, MM is 
month-in-year, DD is day-in-month, F is hexadecimal 
'F' for unpacking. 


Supplies the current date and time to users’ programs or 
system routines in the forms described above. 


Stack on entry and return: 


| OTHER | | OTHER | 
ENTRY: | DATA | RETURN: | DATA | 
| | | ee 
| | | | 
| Oori1 | | Date | 
| | | | 
SP --> | 0or1 | SP --> | Time | 
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Execute Physical 1/0 


XIO 


Inputs: 


(SVC 3) RESIDENT 


The top 16 bytes of the stack are a parameter list 


containing: 
Byte 0: 
Bit 1=1 
Bit 2=1 
Bit 3 =1 
Bit 4=1 
Bit 5=1 
Bit 6=1 
Bit 7 =1 
Bytes 1-3 - 
Byte 4 = 
Bytes 5-7 - 
Bytes 8-9 - 
Bytes 10-11 - 
Bytes 12-14 - 
Byte 15 = 


Flags 
Special block-on-volume-oriented disk 
I/O request - "VOLIO'" - valid only when 


requested by system routines in System 
Mutual Exclusion state or when the 
accessed volume is mounted for 
initialization by the issuing task. 

Block print operation. Data must be 
2K-aligned and is not moved to the 
device's resident print buffer. 

"Halt I/0 Queue’ option (for Disk Mount 
operation). 

Reset UCBSTATNOTOP and UCBSTATNOCODE to 
allow I/0 device being simulated to 
malfunction. 

Issue Return Code = 32 if I/0 issued to 
inoperative workstation. 

Force uppercase printing. 
Telecommunications Option--TRANSMIT or 
RECEIVE. 

Address of Open File Block (OFB) for 
file with the following exceptions: 
When flag bit 7 = 1 (TC option), the OFB 
address is for the VS-DLP communication 
path; when flag bit 1 = 1 (VOLIO option), 
the address of the Volume Control Block 
(VCB) for the disk volume. 

Command byte for I/O Command Word (IOCW). 
Memory address (virtual) for I0OCW if 
read or write command in byte 4. 

Length in bytes for operation (read or 
write command, all devices). 

Unused. 

For disk files only. Block number 
within file (in binary) of the first 
block to be read or written (where the 
first block of a file is block 0). With 
the following exceptions: If VOLIO 
option is selected, the block number 
within the volume (in binary) of the 
first block to be read or written (where 
first volume block is block 0); if TC 
option is selected, bytes 12-14 contain 
bytes 6-8 of the IOCW. 

Unused 
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XIO (SVC 3) 


Outputs: Return codes in the top word of the stack (replacing the 
input parameters). — 


Low-order halfword of return code field - binary return 


codes: 

0 - Success 

4 - Truncation at end-of~extent (non-VOLIO disk only) 

8 ~ Truncation at end-of-cylinder or end-of-track (disk 
only) 

12 - Starting block number beyond end-of-file (non-VOLIO 
disk) or beyond end-of-volume (VOLIO disk) 

16 - Invalid data address or data length. (ata address 


20 
24 


28 


32 


36 


for disk must be page-~aligned; for other devices 
word-aligned. Virtual memory area encompassed by 
the area from data address through data-address plus 
block-size-minus-one must either be in the segment 2 
1/0 buffer area or entirely above the XIO parameter 
list on the stack if the XIO is issued from 
unprivileged state. The specified length must not 
imply spanning of more pages than there are Indirect 
Address List entries for the device.) 

Second XIO on file without intervening CHECK 

TC XIO attempted on an OFB that was not created as 
the result of an ‘IPOPEN' on an IPCB. 

TC XIO attempted on a device reserved exclusively by 
another task. 

XIO0 has been issued to inoperative workstation and 
I/0 has not been issued (bit 5 of option flag must 
be set for issuance of this return code). 

TC XIO attempted on a peripheral processor (DLP) 
reserved exclusively by another task. 


High-order halfword of return code field - residual block 


counts: 


Return codes 0, 12, 16, 20 - Always zero. 
Return codes 4, 8 - Specified block size minus number of 


Note: 


bytes actually read or written. 


If return codes 0, 4, or 8 are set, the I/O 


operation is queued for initiation and a CHECK must 
be issued to test for completion. If return codes 
12, 16, or 20 are set, the operation has been 
suppressed. XIO never waits for I/O completion. 
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XIO (SVC 3) 


Function: Initiates 1/0 operations for the Data Management System, 
as requested by its parameter list. 


The following restrictions on general I/0 capability are 
enforced by the XIO routine: 


All = 


Disk - 


(1) All memory addresses for a read or write oper- 
ation must be valid (present in main memory or 
page faulted) and, unless the requesting 
routine is privileged, must be in the 
user-modifiable segment and either: 


(a) in the I/O buffer area, or 
(b) entirely above the XIO parameter list on 
the stack. 


(1) A block to be read or written must fall within 
the current extent limits of the specified file 
(except for "VOLIO" disk requests). 


(2) The specified memory address must be on a page 
boundary. 


(3) The “VOLIO" option (flag bit 1 = 1) is allowed 
only when requested from within System Mutual 
Exclusion state. 


(4) The length specified for a READ or WRITE oper- 
ation must be a multiple of the page size. 


(5) Indirect data addressing is always used for 
disk 1/0. 


Diskette - Library-Structured 


(1) All restrictions as for other disk. 


Diskette ~ Unstructured 


NOTE: 


(1) A block to be read or written must fall within 
the bounds of the diskette platter (blocks 0 
through 153); otherwise, return code 16 is set. 


(2) The “VOLIO" option is ignored. 


A non-standard addressing option is now supported 
that allows the user to format a_ soft-sectored 
diskette in any combination of sector size and 
density. The use of this option is intended to be 
limited to specialized utilities. User programs 
which employ this option are responsible for per- 
forming direct and sequential I/O on a _physical- 
sector basis. The user program must calculate the 
sector size and addresses, set mode, and set den- 
sity. When non-standard addressing is specified, 
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XIO (SVC 3) 


the XIO SVC will not perform extent validation or 
address translation, but simply passes the address 
to the firmware via the I/O Control Word (CIOCW). 


Tape - (1) 
Printer- 
(1) 
(2) 
Workstation 
(1) 
(2) 


(3) 


Maximum size permitted for tape records is 32K 
bytes. 


Bit 2 of the first byte of the XIO parameter 
list distinguishes between print operations 
through a resident print buffer and multiple- 
line (‘block’) print operations. The data 
length for single~line print operations must be 
not less than 2 or more than 134. The data for 
a block print operation must be on a single 


page. 


The data for a block print operation must in- 
clude record length bytes. The data for single- 
line print operations through a resident buffer 
should include only the printer control char- 
acters and the characters to be printed. 


An Attention Identification (AID) character is 
stored in the current status portion of the 
device Unit Control Block (UCB) on_ successful 
completion of each I/O operation. (Refer to VS 


Principles of Operation Manual or VS _ Operating 


System Services Pocket Guide for a listing of 
these characters.) The AID character also 


serves to indicate whether the workstation 
keyboard is in locked or unlocked state after 
the operation. 


If the device's UCB indicates ‘Keyboard 
unlocked’ when a READ operation is requested, 
the XIO routine will wait for an attention 
interruption from this device. When such an 
interruption is received, the interrupt service 
routine will mark the UCB ‘Keyboard locked' and 
then will allow xXIO to initiate the _ read 
operation. 


Indirect data addressing is always used by xXI0 
for workstation I/0. 
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Link to Another Program 


LINK 


Inputs: 


(SVC 4} NON-RESIDENT 


The top 16 cr 32 bytes of the stack contain a parameter 
list as follows: 


Byte l = 
Bit 0 =1 
Bit 1=1 
Bit 2 =1 
Bit 3 = 0 
Bit 4 = 1 
Bits 5-7 
Bytes 2-9 - 
Bytes 10-16 - 
Bytes 17-22 - 


Flags, as follows: 
Search only system library for member 
(see below). 
Report failure to find the specified 
member, member not executable, member 
already opened (other than Shared 
Read-only) , or password for member or 
directory not provided, or other error 
by returning to location of SVC 
instruction plus 6 (ext instruction 
plus 4), rather than by entering the 
Help Processor. See outputs below for 
return codes in these cases. 
Branch to location of LINK SVC plus 10 
(next instruction plus 8) after 
Setting up to enter new program or 
subprogram, with entrypoint address of 
new program in register 0. (See 
LOADONLY operand description of LINK 
macro in Chapter 4.) 
Must be zero. 
Overriding user program library and 
volume specified in parameter list 
bytes 17-30. 
Must be zero. 
Character string (ASCII) containing name 
of program to be LINKed to. This name is 
used with the current program library 
specification as a member name within a 
library or volume, and the resulting 


complete filename is sought. If such a 
file is not found, the member name is 
used with the system library 


specification, and the resulting complete 
filename is sought. If flag bit 0 above 
is set, only the system library 
specification is used. If flag bit 1 is 
not set, failure to find the program in 
either library causes abnormal 
termination of the issuing task. 

Not examined. 

Character string containing overriding 
user program library's volume serial. 
Totally absent unless flag bit 4=1. 
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LINK (SVC 4) 


Outputs: 


STACK TOP (SP) - - - - 


Bytes 23-30 - Character string containing overriding 
user program library. Totally absent 
unless flag bit 4=1. 

Bytes 31-32 - Not examined. Absent unless flag bit 4=1. 


Register Rl by convention addresses a standard argument 
list to be passed to the program invoked as a result of 
the LINK. 


A new Program File Block is built and chained to the 
active TCB, indicating that a program has. been 
entered. A new Program Exception Element is built and 
enstacked from TCBPXE, indicating that no program 
exception exits are set. Register R14 addresses’ the 
first (doubleword-aligned) address of the newly created 
group of 'static' areas (see below). Register R1 
addresses the argument list passed by the issuer (if 
provided). Other register contents (except register 
15) are unchanged. Static storage areas for the 
LINKed-to program are pushed onto the stack. A single 
word of control information (address of UNLINK' routine 
to be executed on RETURN) follows. This is followed by 
a save area chain word and register save area suitable 
for use with the RETURN macroinstruction (RTC 
instruction). Control register 1 contains the address 
of this save area (as does general register 15) on 
completion of the LINK. The stack on entry to the 
LINKed-to program is as follows: 


ISSUING PROGRAM'S STACK 


| | 
| | 
| AREA | VARIABLE 
| | 
| 'LINK' SVC SAVE AREA | 72 BYTES 
| USER PROGRAM LIBRARY | 
| AND VOLUME BEFORE 'LINK') | 16 BYTES 
| (RESTORED BY 'UNLINK') | 
| LIBRARY, MEMBER, VOLUME | 
| OF PROCEDURE FILE | 24 BYTES 
| IF PROCEDURE INTERPRETER | 
| INITIATED | 
| | 
| 'STATIC' AREA FOR LINKED~-TO | 
(R14) - - - - | PROGRAM | VARIABLE 
| | 
| SAVE AREA FOR 'RTC' TO | 
| ‘UNLINK' SVC | 68 BYTES 


If no linkage can be made to the specified member, the 
above does not occur; but if parameter byte 1, bit 1 
Was set, control passes to the location of the LINK SVC 
instruction plus 6 with binary return codes in the top 
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word of the stack (replacing the input parameters) as 


follows: 
Return code = 0Q- Not a program file, and the procedure 
interpreter cannot be invoked. 
Return code Volume not mounted 


t ou 
> 
I 


Return code 
Return code 


8 - Volume in exclusive use by another user 
All buffers in use when one was required 
by LINK 

16 - Directory not found 

Access to. program's file-protection 
class denied 

20 - File not found 


u 
pa 
NO 

{ 


Return code 
Return code 


Hou 
ry 
co 

I 


Return code 


nhouéoueg 
NO 
> 
! 


Return code Unused 
Return code = 32 - FDX1 and FDX2 conflict detected by 
READFDR 


Return code 
Return code 


36 ~ FDX2 and FDR conflict detected by READFDR 

40 - Invalid parameter passed to READFDR 
(including NL volume type) 

44 - I/0 error on VTIOC 

48 - Unable to read FDR2 record (additional 

extent specifications) 

Invalid program file; unable to complete 

LINK 

Return code = 56 - File open other than shared read-only 


Return code 
Return code 


U 
uw 
NO 

i 


Return code = 


Function: To pass control to a user-level program or subprogram 
not linkage-edited with the issuing program. Also used 
by the command processor to initiate execution of a 
requested program, oor of the system's procedure 
interpreter. 


User parameters to be passed to the invoked program 
must not be in the reentrant program area (segment 1). 


‘Static areas’, as defined, are static only within a 
group of program modules linkage-edited together, and 
will be removed (popped) from the stack by execution of 
the 'UNLINK' supervisor call routine. 
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Get Buffer Space 


GETBUF 


Inputs: 


Outputs: 


(SP) 


(SVC 5) NON-RESIDENT 


A 2-word parameter list on top of the _ stack. The 
lower-addressed word contains the buffer length 
requested, which must be a multiple of the page size 
(2048). The second word of the parameter list is 
ignored on entry. 


A zero return code and the starting address of the 
allocated buffer OR a nonzero return code placed on top 
of the stack: 


Return code = 0 - A buffer area is allocated (Figure 1). 
Return code = 4 - All buffers in use (Figure 2). 
Return code = 8 —- Requested length is not a multiple of 
2K (Figure 2). 
| | 
| preceding data | | preceding data | 
| | 
| buffer start. addr. | 4 bytes | ignored | 4 bytes 
| | | 
| return code = 0 | 4 bytes | non-zero return | 4 bytes 
code 
(Figure 1) (Figure 2) 


Function: To allocate a buffer area as requested. Buffer space 


is taken from the low address end of segment 2. Value 
in control register 2 (the stack limit) may be modified. 
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Free Buffer Space 


FREEBUF 


Inputs: 


Outputs: 


Function: 


(SVC 6) NON-RESIDENT 


Address of the buffer to be returned in the top word of 
the stack. Length of the buffer area to be returned in 
the next word above. This length must be a multiple of 
the page size (2048). 


NOTE: 
In the case of calls by the GETHEAP/FREEHEAP SVC, the 
high-order byte of the word specifying the length of 
the buffer area is set to X'04'. In the case of such 
calls, GETHEAP/FREEHEAP places the address of the 
corresponding subpool block (SPB) in the third word 
from the top of the system stack. 


A return code in the top word of the stack replacing 
inputs: 


Return code = 0 - Buffer deallocated. 
Return code = 4 - Invalid buffer address. 
Return code = 8 - Invalid buffer length. 


To de-allocate a buffer area allocated by GETBUF (SVC 


5). Value in control register 2 (the stack limit) may 
be modified. 
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Halt I/0 Operation 


HALTIO (SVC 12) NON-RESIDENT 


(1) PRINTER OPTION (retained but made obsolete by "General 
Option", below): 


Inputs: 


Outputs: 


word on top of stack 


byte 0: x'00' 
bytes 1-2: ignored 
byte 3: device number of a printer 


HIO instruction issued to the specified device, if a 
valid printer which is in use by the issuing task. If 
an "I/O processor busy" response is received, the 
corresponding Unit Control Block (UCB) is marked, and 
the HIO instruction reissued when an "I/O processor now 
ready" interrupt is received. The issuing task must 
still wait for any outstanding I/O to complete (see SVC 
CHECK). ‘The condition code from the HIO instruction is 
returned in the word on the stack top. 


Function: To speed termination of multiline print operations 


which are to be aborted. 


(2) GENERAL OPTION 


Inputs: 


Outputs: 


word on top of stack 
byte 0: x'80' 
bytes 1-3: OFB address, or VCB address + 1 


none (parameters removed from stack). 
HALTIO should be issued only if an XIO has been issued, 
but the CHECK has not been done. CHECK should be 


issued after HALTIO (as in a normal 
wait-for-completion) . 
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Allocate Additional Extent 


ALEX 


Inputs: 


Outputs: 


Function: 


Note: 


(SVC 14) NON-RESIDENT (No longer available.) 


The top word of the stack addresses an Open File Block 
(OFB) for the file. 


An additional extent is allocated for the given file. 
Subsequently the entries containing extent information 
in FLUB and FDR records of the file are modified to 
record the allocation. A return code is placed on top 
of the stack replacing the inputs: 


- Additional extent allocated 
= Invalid OFB address; no allocation 


Return code 0 
4 
8: = File in INPUT mode; no allocation 
2 
6 


Return code 
Return code 


Return code = 12 - Wrong device type; no allocation 

Return code = 16 - Extent limit exceeded; no 
allocation 

Return code = 20 - All buffers in use; no allocation 

Return code = 24 - Volume full; no allocation 

Return code = 28 - No space in VTOC for FDR2; no 
allocation . 

Return code = 32 - Disk I/O error; VIOC unreliable 


To allocate an additional extent for a disk file. The 
extent size to be allocated is found in FDR1SECEXT of 
the FDR1. If an extent of the size specified in Field 
FLUBSECEXT of the corresponding FLUB is not available 
on the volume, the largest available extent is 
allocated. 


A file has to be opened for exclusive use before ALEX 
is issued. 
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Return From Program Entered By Link 


UNLINK 


Inputs: 


Outputs: 


Function: 


(SVC 15) NON-RESIDENT 


Field ETCBPFB of the task’s Extended Task Control Block 
(ETCB) addressing save area and control information for 
‘UNLINK' use as pushed onto the stack by LINK (SVC 4). 


The program which issued the LINK (SVC 4) to enter the 
issuing program is restored to the reentrant program 
area (segment 1) of the task's virtual address space. 
The previously active program's PFB and all its PFEs 
are released. UNLINK closes shared files OPENed on the 
link level it is destroying, if the user fails to do 
so. UNLINK releases any devices reserved on the level 
it is destroying, if the calling program fails to do 
so. The save area and control information is removed 
(popped) from the stack. The LINKed-to program's 
‘static' area is popped from the stack. UNLINK 
attempts to close those files which were opened at the 
Link level being unlinked (UNLINK determines which 
files should be CLOSEd by comparing a byte in the OFB 
(OFBLINKLEV) , which was set at OPEN time, with the 
current link level being UNLINKed (ETCBLINKLEV)). 
Control is then passed to the program which issued the 
LINK, at the instruction address folllowing the LINK 
SVC. 


To return from a LINKed-to program. This SVC is 
normally issued by code in the system area (segment 0) 
entered as a result of a RETURN sequence in the 
LINKed-to program. The '‘'UNLINK' SVC may, however, be 
issued directly by a program. 
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Cancel Program 


CANCEL 


Inputs: 


Outputs: 


Function: 


(SVC 16) NON-RESIDENT 


Word on top of stack containing address of message _ to 
be displayed. 


Help Processor entered with no return to issuing 
program. Program abnormally terminated when the user 
issues the 'CANCEL' command to the Help Processor. 


To terminate a program in the event of uncorrectable 
program failure, such as: 


(a) exhaustion of a system resource, 


(b) illegal or invalid parameters to an SVC routine or 
other system service program, 


(c) a program-detected condition which cannot be 
Satisfactorily resolved within the program. 


A standard message is generated to notify the user of 
the error situation. The supplied message is also 
displayed. The user cannot immediately resume program 
execution by the ‘CONTINUE’ command. He may, however, 
examine the program by means of the Help Processor's 
debugging facilities, modify the current instruction 
address by means of the 'CHANCE' command, and_ then 
attempt to resume program execution. A program 
terminated by a CANCEL SVC issued by another SVC 
routine cannot be continued. 


The message at the specified address is in the 
following format: 


(1) Four-byte message number in ASCII characters. 
Always required. 


(2) Six-byte issuer identification in ASCII characters. 


(3) Two-byte message length in binary. This is the 
length of the text which follows as (4) here. 


(4) Message text in ASCII characters. If the message 
is of more than one line, an end-of-line is 
indicated by an ASCII ‘new line’ character. No 
line may contain more than 79 characters, including 
the end-of-line indicator. The last (or only) line 
does not require an end-of-line character. 
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CANCEL (SVC 16) 


Message format: 


| 
Message number | Issuer ID | Length | Text | 
| 


SL eR 


| 
| 
| 
0 4 10 12 end 
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Check For Event Occurrence 


CHECK 


Inputs: 


(SVC 17) PARTIALLY RESIDENT 


Eight-byte parameter items. For single-event CHECK, 
the single item is on top of the stack. For multiple- 
event CHECK, the top word of the stack contains the 
address of the list of items. The high-order byte of 
this word (bits 1-7) contains a count of the number of 
items, and bit 0 of this byte is set to 1; the next 
word on the stack is not examined in this multiple- 
event case. For multiple-event CHECK, if the option 
flag (byte 0) in the input parameter list for the event 
is set equal to X'FF', then the particular event is 
bypassed, i.e., no WAIT is done for the event. 


The FORM=LIST option of the CHECK macro can be used to 
build a multiple-event CHECK list on the stack (see 
CHECK macro description for further details). 


Each eight-byte item is as follows. 


(1) 


(2) 


(3) 


(4) 


Normal I/O check (OFB) item: 

Byte 0 zero. 

Bytes 1-3 OFB address. 

Bytes 4-7 Alternate return address to be used in case 
of 1/0 error, or zero. If the low-order 
bit of Byte 7 is on, then completion IOSW 
is returned in general registers 0 and 1. 


VOLIO I/O check (VCB) item: 

Byte 0 zero. 

Bytes 1-3 VCB address plus 1. 

Bytes 4-7 Alternate return address to be used in case 
of I/O error, or zero. If the low-order 
bit of Byte 7 is on, then completion IOSW 
is returned in general registers O and l. 


Timer check item: 
Byte 0 x‘10' 
Bytes 1-7 Ignored. 


Intertask message check item: 

Byte 0 x'20' 

Bytes 1-3 Address of an area in segment 2 in which to 
receive a message. The first two bytes of 
this area must contain its length in bytes 
(binary) including these bytes. This 
length must not be greater than 2016. The 
message (not including its length bytes) is 
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(5) 


(6) 


(7) 


Outputs: 


Function: 
(1,2) 


moved to the area following these bytes and 
truncated if too long for the specified 
area. The area's length bytes are adjusted 
to reflect the length of the message, 
including these bytes. 


Bytes 4-7 The name (CL4) of one of this task's active 
message receipt ports, as established by 
CREATE. 


Workstation program function key check item: 
Byte 0 x'40' 

Bytes 1-3 Workstation device number 

Bytes 4-7 Ignored 


Unsolicited interrupt: 

Byte 0 x'08' 

Bytes 1-3 Number of any device on line 

Bytes 4-7 Address of 8-byte area to receive IOSW 
(must be in user-modifiable buffer area or 
in stack as validated by MCBRWIST) 


TC event: 

Byte 0: x'01' 

Bytes 1-3: The OFB address of the TC device on which 
XIO was issued 

Bytes 4-7: The address of an eight-byte receiving area 
for the completion IOSW, or binary zeroes 
if the IOSW is not desired 


Single-Event CHECK) 
Inputs popped from stack. For 1/0 completion CHECK, a 
Workstation message is displayed if possible on 
‘intervention required’ conditions. See the XMIT SVC 
description for the format of intertask messages after 
a ‘message’ CHECK. 


Multiple-Event CHECK 

One word of inputs popped from _ stack. Second word 
replaced by displacement within parameter item list of 
item corresponding to the event which has occurred. 
(Displacement is from 0, by 8.) Device ‘intervention 
required’ conditions must be handled by the CHECK 
issuer, who must re-issue a CHECK (single- or 
multiple-event) to wait for I/O completion. 


Waits for completion of an I/O operation initiated by 
means of the XIO supervisor call. In the event of a 
permanent error completion (IOSW bit EC set, bits NC 
or IRQ not set), returns to the alternate return 
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(3) 


(4) 


(5) 


(6) 


(7) 


CHECK (SVC 17) 


address. Otherwise returns to the next sequential 
instruction address. If ‘intervention required’ (IOSW 
bit IRQ) is indicated on completion, issues an 


appropriate workstation message if possible, expecting 
either an unsolicited interrupt from the device when 
it becomes ready, or a response when the condition has 
been corrected; may reissue the message if the 
condition has not been corrected; then waits for 
another completion indication. Writes an I/O error 
logging record in the event of a device malfunction or 
main memory parity error. The Volume Control Block 
address option is available only to routines in System 
Mutual Exclusion (SME) state, or which have exclusive 
use 'for initialization’ of the disk volume to which 
the VCB_ refers. (The VCB option is intended for use 
in conjunction with the VOLIO option of the xXIO 
supervisor call.) 


Waits for expiration of a timing interval. The 
issuing program is cancelled if no interval is set. 


Waits for receipt of a message directed to the 
specified port name, which must have been established 
by the issuing task by means of the CREATE SVC. 


Waits for a program function key to be struck at the 
specified workstation. The issuing program is 
cancelled if an un-CHECKed I/0 operation (XIO) has 
been issued to the specified workstation, or if that 
workstation is not reserved for use by this task. 


Waits for an unsolicited interrupt from a workstation 
or printer. For a workstation, this CHECK option 
Waits for a program function key whether the keyboard 
is locked or not. The issuing task will be cancelled 
if the device is not reserved for use by the issuing 
task or an unCHECKed I/O is outstanding. The IOSW of 
the unsolicited interrupt will be moved to the 8-byte 
area specified in the input parameter list. 


Waits for telecommunications reception or trans- 
mission. Also waits for unsolicited interrupt from 
telecommunications device. If the TC 1/0 completes 
with an error because of missing device microcode or 
missing peripheral processor microcode, the error is 
logged but the microcode is not loaded. 


Sequencing rules for alternation of RECEIVE/TRANSMIT 
followed by CHECK TCIO are enforced by the XIO SVC 
routine. XIO also checks that the device and DLP are 
not exclusively reserved by another task, and that the 
device is currently open (IPOPENed by this task). 
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CHECK TCIO may be issued without any previous 1/0 
being issued provided the device is reserved by the 
calling task. In this case the CHECK is taken to be 
for an unsolicited interrupt from the DLP on_ the 
specified device. To receive an unsolicited interupt 
from the DLP, at least one of the devices on the DLP 
must have been IPOPENed and reserved by the caller. 
For this option, an IOSWADDR must be provided for the 
transfer of the IOSW to the caller. 


If an unsolicited IOSW was returned by the DLP and the 
user has issued an XIO and is awaiting the completion 
IOSW to that I/0, the unsolicited IOSW does not cancel 
the effects of that condition. That is, the user is 
able to receive the unsolicited IOSW, and allowed to 
reissue the CHECK TCIO to receive the IOSW in response 
to the xXIO. The general status byte of the IOSW 
returned will indicate to the user that it is an 
unsolicited IOSW rather than a normal IOSW in response 
to an X10. If the user has received an unsolicited 
TIOSW while waiting for the completion of an 
outstanding XIO, he must wait for the completion of 
the XIO by resubmitting the CHECK TCIO before issuing 
another XIO on the specified VS/DLP I/O channel. 


The issuing task will be cancelled if the device is 


not reserved for use by the issuing task or an 
unCHECKed I/O operation is outstanding. 
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Read Volume Table Of Contents Block 
READVTOC (SVC 19) NON-RESIDENT 


Inputs: The top word of the system stack addresses’ the 
following argument list: 


| 
| preceding data 
size depends 


not used on options 


| 
| 
| 
| directory name/ 


| 
| 

| 
| 

| 

| 

| 
d | 
| | 
| 
| 
| 
| 
| 
| 
4 | 
| 
| 


| OFB ptr (First 4 bytes) /not use 8 bytes 
| starting item number = n >= 0 2 bytes 
| count number = m >= 0 2 bytes 
| not used 1 byte 
| option number = 0, 1, 2, 3, or 1 byte 
Input Argument List | volume name 6 bytes 


Option number = 0 - To read VIOC attributes: 


i. VTOC extents in use; no. of 
unused blocks in VTOC. 255 
is returned if the number of 
unused blocks is greater than 
or equal to 255. 


ii. Total no. of directories on 
volume; total no. of files on 
volume. 


iii. Total no. of free extents on 
volume; total size of free 
extents. 


iv. m largest free extents on 
volume. 


Option number = 1 - To list m free extents starting from 


nth (from 1) free extent in VTOC. 


Option number = 2 - To list m directory names and 
corresponding no. of files in 
directory starting from nth 


directory name (from 1) in VTOC. 
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Outputs: 


Option 
Number 0 


Output 
Argument 
List 


il 
Ww 
i 


Option number 


Option number = 4 - 


To list m file names. starting 
from nth file (from 1) in 
specified directory. 


To read in m consecutive VTOC 
Control blocks starting from nth 
block in VITOC and copy into a 
file specified by the given OFB 
pointer. 


A return code on top of system stack replacing inputs. 


Return code = 0 - Requested function performed. 

Return code = 4 - Invalid argument list address. 

Return code = 8 - Volume not mounted. _ 

Return code = 12 - Volume used exclusively by other 
user. 

Return code = 16 - All buffers in use. 

Return code = 20 - Invalid option request or OFB 
address. 

Return code = 24 - Directory not found. 

Return code = 28 - VTOC error; FDX1 and FDX2 do not 
agree. ; 

Return code = 32 - Disk I/O error; VTOC unreliable. 

When return code = 0, the input argument list is 


replaced by one of 


depending on the option specified. 


emcee fe wre fcc me fe fe fe rn fee em fee fe re J ree ee ee eee Jee ee 


mth largest free extent start & end block 
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the following output argument lists 


number. | bytes 
| | 
; | 
lst largest free extent start & end block | 
number. | 6 bytes 
Total size of free extents. | bytes 
Total no. of free extents. | bytes 
Total no. of files on volume. | bytes 
Total no. of directories on volume, ! bytes 
3rd VIOC extent start & end block numbers. | bytes 
2nd VTOC extent start & end block numbers. | bytes 
lst VIOC extent start & end block numbers. ! bytes 
Number of VIOC extents in use. : byte 
Number of unused blocks in VTOC. ! byte 


Option 
Number 1 


Output 
Argument 
List 


Option 
Number 2 


Output 
Argument 
List 


Option 
Number 3 


Output 
Argument 
List 


READVTOC (SVC 19) 


(n+m—-1) st free extent start & end block no. 


nth free extent start & end block no. 


Total no. of free extents listed <= m 


Total no. of free extents on volume 


| 
| No. of files in directory name (ntm-1) 

| 

| directory name ntm-1 

. 


| No. of files in nth directory name n 


e 


| Directory name n 


] 
| 

| Total no. of directories listed <=m 
| 
| 


Total no. of directories on volume 
Filename ntm-1 


Filename n 


| 

| 

| 

| . 
| 

| 

| 

| Total no. of files listed <= m 
| 


| Total no. of files in directory 
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bytes 


bytes 
bytes 


bytes 


bytes 


bytes 


bytes 
bytes 
bytes 


bytes 


bytes 


bytes 


, bytes 


bytes 


READVTOC (SVC 19) 


Option 
Number 4 


Output 
Argument 
List 


Function: 


Note: 


| 

| | 

| not used | 16 bytes 
| | 

| | 

| # of blocks read (<m) | 2 bytes 
| Total VIOC size in blocks | 2 bytes 


Additional Output for option number 4: nth through 
(ntm-1)st VTOC control blocks copied to the file 
specified by the given OFB. 


To read the specified information from VTOC of a 
specified volume. 
The size of the input argument list must be big enough 


to hold the desired output argument list for successful 
operation. 
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Request Parameters 


GETPARM 


Inputs: 


(SVC 20) 


NON-RESIDENT 


Parameter list of eight or twelve bytes on stack top: 


(1) One-byte Request Type Indicator: 


Bits 0-3: 


0 


Bit 4: 


Bit 5: 


Header Type/Acceptable Response Designator 


Request for Information. Acceptable 
response is modification of variable fields 
with completion signaled by pressing the 
ENTER Key or any enabled PROGRAM FUNCTION 
KEY. By default, all PFKs are disabled. 


Request for Selection. Acceptable response 
is selection indicated and signaled by 
pressing the ENTER key or any enabled 
PROGRAM FUNCTION KEY. By default, all PFKs 
are enabled. 


System Request for Information. Reserved 
for use by OPEN and SYSTEM INITIALIZATION. 
The generated display header is different 
from that for type 0. Acceptable response 
is the same as that for type 0. 


System Request for Device Action. Reserved 
for use by OPEN, MOUNT , and CHECK. 
Acceptable response involves performance of 
machine operator duties with completion 
signaled by an interrupt from the indicated 
device, or by pressing the ENTER or any 
enabled PROGRAM FUNCTION KEY. By default, 
only PFK #16 is enabled, and by convention, 
it is used to allow the user to request 
termination of the device action request. 


If set, indicates that the ENTER key will be 
accepted as a response to the GETPARM (ENTER 
key disabled), in addition to any keys 
specified in the PF key mask. This bit is 
ignored unless bit 5 is set. 


PFK Mask Present Indicator. 
Default Mode. PFK's are enabled or disabled 


according to default values. The PFK mask 
should not be present in the parameter list. 
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1 = Override Mode. PFK's are disabled as 
indicated by the PFK mask which must be 
present in the parameter list. 


Bit 6: Request Sequence Identifier 


0 = TYPE I - Initial request for specification 
of information, selection among 
alternatives, or response. 


1= TYPE R - For correction of information, 
selection, or response just received as a 
result of the previous request. 


Bit 7: User-Interaction Suppressor 
0 = Normal Mode 


(This mode will generate a workstation interaction 
even if the default data in the receiving fields of 
all Field Format Control Blocks satisfy lexical 
requirements for correctness. The workstation 
interaction is suppressed only if the 
procedure-specified data supplied is lexically 
correct and is sufficient in conjunction with the 
default data to completely satisfy the request.) 


1 = Default Mode 
(This mode is intended for use by OPEN only. This 
mode accepts procedure-supplied data if available, 


but will not generate a workstation interaction 
unless a field default value is lexically in error.) 


(2) Three-byte address of message to be displayed. 
(See format.) 


(3) One-byte zero, or for Device Action request only, 
the device number of the device requiring service. 


(4) Three-byte address of Parameter Group Control 
List. (See format.) 
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(5) Optional four-byte Program Function Key Mask. 


bit 


8(SP) 


4 (SP) 


0 (SP) 


4 (SP) 


0 (SP) 


GETPARM (SVC 20) 


Each 


indicates whether the corresponding PFK should 
be enabled or not. The high-order bit corresponds 
to PFK. 


PFK enabled 
PFK disabled 


ony 
tou 


| Optional Program Function Key Mask | 


| 
{ Device | | 
| no. or O | A(Control List) | 
| | 
| Req. Type | A (Message) | 
| | | 
| Device | | 
| no. or O | A(CControl List) | 
| | | 
| Req. Type | A (Message) | 
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The 


message at the specified address is in the 


following format: 


| | 

| Message Number | Issuer ID | Length | Text | 

| | | | | 

0 4 10 12 end 

The fields in this format are: 

(1) Four-byte message number in ASCII characters. This 
number is displayed in the GETPARM header on any 
associated screen transactions. 

(2) Six-byte issuer ID in ASCII characters. This ID is 
displayed in the GETPARM header on any associated 
screen transactions. 

(3) Two-byte message length in binary. This is the 
length of the text which follows. 

(4) Message text in ASCII characters. If the message 


is longer than 79 characters, an end-of-line can be 
indicated by an ASCII "new-line™ character. 


No line may be longer than 79 characters excluding 
the end-of-line indicator. The message text is 
displayed beginning in column 2 of line 7. Each 
new line begins in column 2 of the next line. 
Lines longer than 79 characters are truncated. The 
last line does not require an end-of-line indicator. 
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The Parameter Group Control List is in the following 
format: 


+0 


PRNAME 


| 
+8 PF key field | # of fields 


FIELD N FORMAT 
CONTROL BLOCK 


| 

| 

| 

| 

| 

| 

| 

| 

| 

| | 

+10 | | 
| | 

| FIELD 1 FORMAT 

| CONTROL BLOCK | 

| | 

| 

| | 

| | 

| | 

| | 

| | 

| | 

+10 + BL | | 
1 | 

| FIELD 2 FORMAT | 

| CONTROL BLOCK | 

| i | 

| 

| | 

| | 

| | 

| | 

| | 

| | 

| | 

| | 

| | 

n-1 | 
| | 

+10 + BL | 
i | 
i=1 | 
| 

| 

| 

| 

| 

| 
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fields in this format are: 


Eight-character, left-justified Parameter Reference 
Name (i.e., PRNAME). 


One-byte receiving field for AID character of 
program function key response. (This field may be 
set by procedure specification of a function key 
number. ) 


One-byte binary count - number of Field Format 
Control Blocks. 


following is repeated for each displayable field. 

eee (n) 

Variable length Field (display and entry) Format 
Control Block. There are two formats for the Field 
Format Blocks: one for control of the 


keyword/receiving field pairs, and the other to 
control the use of displayable imbedded text. 
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The Field Format Control Blocks for the 
keyword/receiving field pairs are in the following 
format: 
| | 
+0 | LINE ADVANCE | SPACE ADVANCE | 
{| _ COUNT | _—*CoUuNT | 
| | | 
+2 | ERROR FLAG & | RECEIVING | 
| RESTRICTIONS |FIELD LENGTH —1| 
| | 
+4 | | 
| 
KEYWORD { 
| | 
| | 
| | 
| 
| | 
+12 | | 
| | 
| 
| 
| | 
RECEIVING FIELD | 
| | 
| 
| | 
| | 
| | 
| | 
| | 
The fields in this format are: 


(2) 


(3) 


One-byte binary Line-Advance-Count for display 
control. 


One~byte binary Space-Advance-Count for display 
control. (Line advance takes place before space 
advance. Both take place before display of keyword 
and receiving field.) 


One-byte binary Field Error Flag and Receiving 
Field Entry Restriction Indicator: 


Bit 0: Field Error Flag (1 = error) (Set _ by 
program to draw attention to fields in 
error - Reset by GETPARM.) 


Bits 5-7: Entry restrictions 
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Character-string 


No restrictions on content; maximum usable 
field length is 68 characters. 


Positive integer 


Nonblank response need not be justified, 
but must consist entirely of the numerals 
0-9 with leading and trailing blanks 
ignored. All blanks will be treated as a 
legitimate NULL specification. Field 
length is restricted to 16 characters. 


Numeric 


Response must consist entirely of the 
numerals 0-9 optionally containing one 
decimal point and optionally preceded by a 
+ or -. Leading and trailing blanks will 
be ignored. All blank response will be 
treated as a legitimate NULL response. 
Field length is restricted to 16 characters. 


Uppercase alphanumeric 


All entered letters will be converted to 
uppercase. A legal nonblank response must 
be left-justified and consist entirely of 
the numerals 0-9, the letters A-~Z, the 
national characters (@, #, or $), and 
trailing blanks. An all blank response 
will be treated as a legal NULL response 
indicator. Maximum usable field length is 
68 characters. 


Uppercase hexadecimal 


All entered letters will be converted to 
uppercase. A legal nonblank response need 
not be justified, but must consist entirely 
of the numerals 0-9, and the letters A-F 
with leading and trailing blanks ignored. 
All blanks will be treated as a legitimate 
NULL specification. Maximum usable field 
length is 68 characters. 


Uppercase Character String 
All letters are converted on entry to 


uppercase; maximum usable field length is 
68 characters. 
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7 = Alphanumeric Limited 


All entered letters will be converted to 
uppercase. Legal nonblank response will 
be left-justified, begin with a letter 
A-Z, or one of the national characters 
(@, #, or $), and consist entirely of the 
numerals 0-9, the letters A-Z, the 
national characters, and trailing 
blanks. An all blank response will be 
treated as a_ legal NULL response 
indicator. Maximum usable field length 
is 68 characters. 


(4) One-byte binary receiving field length minus one 
(in characters) . 


(5) Eight-character, left-justified keyword used for 
display purposes (and to support noninteractive 
access via the Procedure Interpreter). 


(6) Variable-length receiving field with default or 
current value in place. ; 


The Field Format Control Blocks for imbedded text are in 
the following format: 


| { 
+0 | LINE ADVANCE | SPACE ADVANCE | 
| COUNT COUNT | 
| | 
+2 «| =] | TEXT LENGTH | 
| | MINUS ONE | 
| | 
+4 | | 
| | 
| | 
| | 
| | 
| | 
| | 
| TEXT | 
| | 
| | 
| | 
| 
| | 
| | 
| | 


The parameters in this format are: 


(1) One-byte binary Line-Advance-Count for display 
control. 
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Outputs: 


(2) One-byte binary § Space-Advance-Count for 
display control. (Line advance takes place 
before space advance. Both take place before 
display of keyword and receiving field.) 

(3) 1 (=255). 


(4)  One-byte binary text field length minus one 
(in characters) . 


(5)  Variable-length text field. 


(1) Receiving fields as modified by user 
interaction or procedure specified data. 


(2) Program Function Key Receiving Field set to 
accepted AID byte or procedure specified value. 


(3) Field error flags in control list reset to 
ZERO. 


(4) Input parameters popped from stack upon return. 


Function: The GETPARM SVC enables user programs (and OPEN) to 


solicit and accept run-time parameter information, and 
to display and wait for acknowledgment of run-time 
messages. The requested information (or response) is 
gathered either through direct interaction with the user 
(at the workstation) or by calling prespecified data in 
the procedure which invoked the program. The program 
issuing the GETPARM SVC need not be aware of the data 
source; any interactive program that communicates with 
the user exclusively using GETPARM requests which can be 
identified and anticipated, can also be run in batch 
mode from a procedure. The parameters supplied to 
GETPARM are primarily related to the generation of a 
meaningful display. 


When displayed at the workstation, the GETPARM request 
generates a header section, followed by the program- 
supplied message, followed by the keyword identified 
receiving fields and imbedded text section. These 
requests are divided into three functional types. A 
request for information should be indicated whenever one 
or more receiving fields are present. The expected user 
response is to modify one, all, or none of these fields 
and to signal when ready by pressing the ENTER key. 


A request for selection should be indicated when a list 
of valid choices has been displayed (rather than 
modifiable receiving fields) and the expected user 
response is to identify and signal his choice by 
pressing one of the program function keys or the ENTER 
key. A request for acknowledgment should be indicated 
when the user has been asked to take some operator 
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action, or merely acknowledge receipt of an infor- 
mational message. In this mode, the expected user 
response is to press the ENTER key as a ready signal. 


When the issuance of a GETPARM SVC results in a screen 
display, the contents of the screen (if in use) are 
saved and are restored when the user indicates 
completion of his response. 


GETPARM parameters should always be encoded with the 
assumption that they must be capable of generating an 
acceptable display. Lines 1 through 6 of the displays 
are reserved for system-generated headers which assist 
the user in responding to the GETPARM request. The 
headers are varied according to request type with spe- 
cial handling given when the issuer is OPEN. These 
lines include display of the message number and the 
issuer ID in the fixed format section of the message. 
The message text is placed on the screen beginning with 
column 2 of line 7. One additional line beginning at 
column 2 is displayed for each line-feed encountered. 
The line-feed is not displayed and does not use a char- 
acter position. The maximum length for a line of text 
is 79 characters. The message section is completed with 
a blank line. 


The receiving field display section begins with column 2 
of the next line after the message section. Each 
receiving field is displayed with its associated keyword 
as follows: 


(a) The screen line position advances the indicated numn- 
ber of lines from the current position. If line ad- 
vancement takes place, column position is set to 2. 


(b) The screen column position advances the indicated 
number of spaces from the current position. 


(c) The eight-character keyword, followed by a blank, 
followed by an “="" character, followed by a blank, 
followed by the receiving field, followed by a blank 
is displayed. If any part of the receiving field is 
not on the screen, the keyword and field will not be 
displayed and will not be validated. Fields flagged 
as being in error will be blinked to attract user 
attention. 


Each imbedded text field is displayed as follows: 
(a) The screen line position advances the indicated num- 
ber of lines from the current position. If line ad- 


vancement takes place, column position is set to 2. 


(b) The screen column position advances the indicated 
number of spaces from the current position. 
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(c) The variable length text is displayed followed by a 
blank. If any part of the text is not on the 
screen, no text is displayed. 


The message text plus the receiving field display will 
be truncated if it exceeds 18 lines of displayable 
information. 


Default or current information in the receiving fields 
is displayed as is without regard for entry control 
information. However, this information will be flagged 
for user correction if the format does not match when 
the user presses the ENTER key. 


After the display is generated, the cursor is placed at 
the beginning of the first receiving field, or on type 
"R" request, to the beginning of the first keyword field 
which has an error flag set. A read is then issued to 
wait for a legal user response. Upon a signal from the 
user, the receiving fields are checked for legal con- 
tents and, if all are correct, are moved into the pro- 
gram's receiving fields. If any are in error, an error 
message is generated in the display header, the field in 
error is blinked, and another read is issued. When the 
user has successfully supplied the information of his 
choosing, control is returned to the user's program, and 
if the screen was in use, its contents are restored. 


The user can suspend GETPARM processing and enter the 
Help Processor by pressing the HELP key. The screen 
will be saved as is, and the issuance of a CONTINUE 
command will return control to GETPARM with a restored 
screen. The user can then reenter his program by 
completing his response to GETPARM. 


The program using GETPARM cannot assume that the user's 
response (or the accessed procedure data) will be 
valid. Consequently, the displayable parameters 
presented to GETPARM include a parameter-group receiving 
section with imbedded explanatory text, and a separate 
message section. The GETPARM user is expected to 
initiate a sequence of repeated requests until an 
acceptable response is received. During this sequence 
the requested information should be the same, while the 
message changes to best explain the difficulties 
encountered in the previous responses. 


The request sequence indicator is used by GETPARM to 
differentiate between an initial request and a _ request 
for correction of material which the program did not 
find satisfactory. An initial request (Type "I") will 
be satisfied using procedure-specified data (located 
using the keywords and the parameter reference name) if 
available, generating a user~interaction only if all 
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such data has been exhausted. (Each initial request 
with a given PRNAME will consume one equivalent 
specification statement in a procedure.) A request for 
respecification (Type "R") will always generate a 
user-interaction. 


If user-interaction suppressor bit is set, initial re- 


quests will access procedure-specified data if available, 
but will not ordinarily generate a user-interaction. 
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READFDR (SVC 24) 


NONRESIDENT 


Inputs: Two words on the top of the stack, as follows: 


Bytes 0-3: 


Bytes 4-7: 


Address of the parameter list, in the format 
given below. 
Ignored on input but used for output. 


Parameter List Format: 


Bytes 0-7: Primary search library name (LIBRARY) 

Bytes 8-15: File name (FILE) 

Bytes 16-21: Volume name for primary search library 
(VOLUME) 

Byte 22: Option flags: 

bits 0-3 Reserved 

bit 4 = 1 Alternate search library and volume (last 
two entries in parameter list) are 
present. 

bit 5 =1 Read both the FDR1 and the first FDR2 (if 
any), in ascending order, into the 
160-byte area specified by the FDR 
receiving area. The FDRn field is 
ignored. 

bit 6 =1 Read the file prologue along with other 
options that are set. 

bit 7 =1 Read the file prologue only. 

Byte 23: FDR record number: 

FDRn = 0 if 80 bytes of FDR1 are to be 
read; = 1 if 80 bytes of first FDR2 
are to be read; = 2 if 80 bytes of 
second FDR2 are to be read, etc. 

Bytes 24-27: Address of FDR receiving area (AREA) 

Bytes 28-31: Address into which to read _ the file 
prologue. (Used only when bit 6 or 7 is 
set in option flag.) 

Bytes 32-35: Reserved; should be zeros. 

Bytes 36-43: Alternate search library name (ALTLIB) 

Bytes 44-49; Volume name for alternate search library 
(ALTVOL) 

Note: The parameter list for READFDR may not be located in 


segment 1 (user program reentrant segment). 


Outputs: A return 


inputs: 


code in the top word of the stack replacing 
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Return code 
Return code 
Return code 


- File label copied into memory 

Volume not mounted 

~ Volume exclusively used by other 

user, no read 

Return code 12 - All buffers in use, no read 

Return code Library not found 

Return code = 20 - File label not found 

Return code = 24 - Attempt to read a file prologue 

when none was present. 

Return code = 28 - Unused 

Return code = 32 - VIOC error. FDX1 and FDX2 do not 
agree 

36 ~ VTOC error. FDX2 and FDR do not 
agree 

4) - Invalid input parameters 

44 - Disk I/O error. Volume Table of 

Contents unreliable 


tou 
off © 
t 


"ou 
e 
oO 

1 


Return code 


Return code 
Return code 


If return code=0 only, the next word on the stack 
contains the disk address of the FDR record read, in 
the following format: 


Byte 0 (high-order) - Record on block, from 0. 
Bytes 1-3 - Block on volume, from 0. 


If return code nonzero, the contents of this word are 
irrelevant on output. 


When the alternate library name is supplied, the 
library name and volume name entries in the parameter 
list are modified if required to indicate the library 
in which the specified file was found. The alternate 
library is searched after the normal (Filenamel) 
library. 


To locate a disk file in the Volume Table of Contents 
of the specified volume and copy its label (File 
Descriptor Record) into the specified 80-byte memory 
area. 


Also to read the file prologue (only supported for 


Word Processing files) and return the prologue to the 
caller in the specified area. 
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RENAME (SVC 26) NONRESIDENT 
Inputs: The top word of the stack addresses an argument list of 
the following format: 
Bytes 0-7: Old library name 
Bytes 8-15: Old file name or ignored 
Bytes 16-23: New library name (if only library is to 
be renamed) or new file name. (For "Full 
RENAME ,"' the new file name.) 
Bytes 24-29: Volume name 
Byte 30: Option flag 
bit 0 =1 Bypass expiration date check 
bit 1 =1 Rename a library (Bytes 16-23 of the 
parameter list then contain a new library 
name) . 
bit 2 =1 File access rights for this request to be 
limited to user LOGON rights. 
bit 3 =0 Reserved; must be zero. 
bit 4 =1 "Full RENAME" (i.e., rename both file and 
library -- Bytes 32-39 must contain the 
new library name. 
bit 5-7 Reserved; must be zero. 
Byte 31: Not used. 
Bytes 32-39: New library name (for "Full RENAME"). 
Outputs: The file or library identified by the old name is 
renamed (old file name is ignored for rename of just a 
library). Consequently the contents of the file name 
or library name entries of the file index records 
and/or file descriptor record in the Volume Table of 
Contents are replaced by the new file name and/or 
library name. 
A return code is placed in the top word of the _ stack 
replacing inputs: 
Return code = 0 - File or library renamed. 
Return code = 4 - Volume not mounted. 
Return code = 8- Volume used exclusively by other user. 
Return code = 12 - All buffers in use, no rename. 
Return code = 16 - Library not found. 
Return code = 20 - File not found. 
Return code = 24 - Update access to some fileprotection 
class denied, no rename. 
Return code = 28 - Unexpired file, no rename. 
Return code = 32 - File in use, no rename. 
Return code = 36 - VTOC error. FDX1 and FDX2 do not 
agree. 
Return code = 40 - VTOC error. FDX2 and FDR do not agree. 
Return code = 44 - Invalid argument list address. 
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Function: 


RENAME (SVC 26) 


Return code = 48 - I/O error. Volume Table of Contents 

unreliable. 

Return code = 52 - New file name or library name already 

exists, no rename. 

Return code = 56 - New file name invalid (or first 
character '#‘'), no rename. 

60 - The VTOC is currently full -- 
insufficient space exists for the new 
FDX1/FDX2 ("Full RENAME" only). 

Return code = 64 - Reserved bits in the Parameter list 

Options Byte are non-zero. 


Return code 


To change the name of a disk file or library on a 
volume. The structure of the Volume Table of Contents 
may be affected in the case of a "Full RENAME."" The 
file must not be in use (open) when the RENAME is 
attempted, or it will fail (with return code 32). 
Similarly, no file in a library to be renamed may be in 
a file protection class for which the issuer does not 
have update access rights. Likewise, no file in such a 
library may be unexpired unless option flag bit O is set. 
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SCRATCH (SVC 27) NONRESIDENT 
Inputs: The top word of the stack addresses an argument list of 
the following format: 
| | 
| not used | 1 byte 
| | 
| option flag | 1 byte 
| 
| volume name | 6 bytes 
| | 
| file name or ignored | 8 bytes 
| | 
Argument list | library name | 8 bytes 
The option flag indicates whether password checking is 


to be bypassed: 


(scratch library 


if all files 


expired, and update-accessible). 


File name: 


When specified, 
member in the library to be deleted. 


to bypass expiration date check. 


indicates 


bit 1 (scratch entire library) is set. 
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| 

| ‘1' if file access rights for this request 
| to be limited to user logon rights 

| '1' to scratch all closed and expired files 
| in library for which update access 
| 

| 


is allowed 
are closed, 


the specific 


Ignored if option 


Outputs: 


Function: 


SCRATCH (SVC 27) 


The file descriptor record of the file specified by the 
given filenames is scratched from the Volume Table of 
Contents of the specified volume and the disk space 
occupied by the file is deallocated. If an entire 
library is to be scratched, the file descriptors for 
all included files are eliminated and all space is 
deallocated. 


A two-field return code on top of the stack replacing 
input: 


Byte 1 Byte 2 Byte 3 Byte 4 


| | 
| | | 
| 

| | 

| return code field 

Lost extent size in blocks during scratch 


file or library (size equals zero for no 
extent lost) 


Return code 
Return code 
Return code 
Return code 
Return code 
Return code 


0 - File or library scratched from volume 
4 - Volume not mounted 
8 - Volume used exclusively by other user 
12 - All buffers in use, no scratch 
16 - Library not found 
20 - File not found 


uo 
NO 
> 

| 


Return code Update access to file protection 
class denied (singlefile scratch 
only) 

Return code = 28 - Unexpired File, no scratch 


(singlefile scratch only) 

Return code = 32 - File in use, no scratch 

Return code = 36 - VIOC error. FDX1 and fFDX2 do not 

agree 

VTOC error. FDX2 and FDR do not 

agree 

Return code = 44 - Invalid argument list address 

Return code = 48 - I/O error. Volume table of contents 
unreliable 

52 - Open, protected, and/or unexpired 
file(s) bypassed in scratching 
library 


il 

7 

rn) 
! 


Return code 


Return code 


To delete a disk file or library from a volume. 


Note: Scratching the only file in a library 
(directory) eliminates the library itself. 
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EXTRACT (SVC 28) NONRESIDENT 


Inputs: A variable-length parameter list on the stack top. The 
high-order byte of the lowest-addressed word designates 
the class of data required. 


Class codes are: 


Binary 0 ~- Limited output 

Binary 1 - Full output 

Binary 2 ~ Program exception PCW 

Binary 3 - User-supplied list of items 
requested 

Binary 4 - User-supplied list of items 
requested with additional input 
required 

Binary 5 to 255 - Reserved 


For classes 0, 1, and 2, a one-word parameter is supplied. 
The high-order byte of the word designates the class code 
(i.e., binary 1, 2, and 3, respectively). The three low- 
order bytes contain the address of a segment 2 area to 
receive the data (which must be on the existing stack or in 
the I/O buffer area). 


For class 3, the parameter list consists of a header word 
and a list of 8-byte entries corresponding to the requested 
entries. The high-order byte of the header word designates 
the class code (i.e., binary 3), the next lower byte is 
reserved and should be zero, the two low-order bytes 
contain a count of the item entries that follow. Each 
8-byte entry is in the following format: 


Bytes 0-3 - Item identifier code. See EXTRD macro for a 
list of possible codes. 
Bytes 4-7 - Address of a segment 2 area to receive the item. 


For class 4, the parameter list consists of a header word 
and a list of 8-byte entries corresponding to the requested 
entries. The high-order byte of the header word designates 
the class code (i.e., binary 4), the next lower byte is 
reserved and should be zero, the two low-order bytes con- 
tain a count of item entries that follow. Each 12-byte 
entry is in the following format: 


Bytes 0-3 - Item identifier code. See EXTRD macro for a 
list of possible codes. 

Byte 4 - Length in bytes of area to receive the data. 

Bytes 5-7 - Address of a segment 2 area to receive the data. 

Bytes 8-11- Address of additional input for this item. See 
EXTRD macro for a description of these items. 
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Outputs: For classes 0-2, data in area addressed by word on 
stack, as follows, by ascending addresses: 


Class 0; 


(1) Total physical area in bytes not currently 
resident (4 bytes). 

(2) Number of files which current task may open 
simultaneously (2 bytes). 

(3) Workstation number associated with requesting 
task, or -1 if none (2 bytes). 

(4) Remaining stack space in bytes after return 
from 'EXTRACT' (4 bytes). 


Class 1: 


(1) Total physical area in bytes not currently 
resident (4 bytes). 

(2) Number of files which current task may open 
simultaneously (2 bytes). . 

(3) Workstation number associated with requesting 
task, or -1 if none (2 bytes). 

(4) Remaining stack space in bytes after return 
from 'EXTRACT' (4 bytes). 

(5) One day in clock units (4 bytes). 

(6) System default library's volume name (6 bytes).. 

(7) System default library name (8 bytes). 

(8) Task's default printer number, or -1 if none 
(2 bytes). : 

(9) User program library volume (6 bytes). 

(10) User program library name (8 bytes). 

(11) Current file-access bit map for ‘execute’ 
access from Program File Block (PFB--4 bytes). 

(12) Default nonoutput volume for 'OPEN' (6 bytes). 

(13) Default nonoutput library name (8 bytes). 

(14) Current file-access bit map for 'read' access 
from Program File Block (4 bytes). 

(15) Default output volume for 'OPEN' (6 bytes). 

(16) Default output library name (8 bytes). 

(17) Current file-access bit map for ‘update’ access 
from Program File Block (4 bytes). 

(18) Number of segment 2 buffer pages currently 
available (2 bytes). 

(19) Print output mode (1 byte). 

(20) Default output file-access protection class, or 
blank (1 byte). 

(21) User logon identification (3 bytes). 

(22) Paging priority from TCBSCC (1 byte). 

(23) Suggested lines-per-page for print files 
(1 byte). 

(24) Operating System version number (A _ packed 
number VVRRPP, where 'VV' is the version, 'RR' 
is the revision, and 'PP' is the patch level) 
(3 bytes). 
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Class 2: 


(1) 


Class 3: 


Program Control Word (PCW) at time of most 
recent program exception for which a user exit 
was specified (8 bytes). 


Data is returned as specified in the parameter 
list. (See EXTRACT macroinstruction description 
for possible values.) 


Class 4: 


ID=EXTRDIDDEVICE: 


(1) 
(2) 
(3) 
(4) 
(5) 
(6) 


(7) 


Device class (1 byte). 

Device type (1 byte). 

Usage - '‘EX' (exclusive), '‘SH' (shared), or 
"DT' (detached) (2 bytes). 

Task identifier of device owner, or -1 if none 
(4 bytes). 

Volume name of removable volume (disk or tape 
only). Blank if nothing mounted. (6 bytes). 
Volume name of fixed volume (disk only). Blank 
if nothing mounted (6 bytes). 

4 bytes of binary zeros (reserved). 


ID=EXTRDIDVOLUME : 


(1) 
(2) 
(3) 
(4) 


(5) 
(6) 
(7) 
(8) 
(9) 


(10) 
(11) 


(12) 


(13) 


Device address, or ~-1 if volume not mounted 
(1 byte). 

Volume type: 'F' for fixed, 'R' for removable, 
or blank if not mounted. (2 bytes). 

Label type: '‘SL' (standard label), 'NL' (no 
label) , or blank if not mounted. (2 bytes). 
Usage--'SH' (shared), 'RR’' (restricted re- 
moval), 'PR' (protected), "EX' (exclusive), or 
blank if not mounted.. 

Task identifier of volume mounter, or ~1 if 
none (4 bytes). 

Blocks per cylinder (2 bytes). 

Maximum transfer in bytes (2 bytes). 

Cylinders per volume (2 bytes). 

Cylinders per physical volume, including bad or 
unused blocks (2 bytes). 

Number of files open on this volume (2 bytes). 
Sector type (diskette only): soft sector (S), 
hard sector (H) 

Addressing in effect (diskette only): 
Non-standard (N), Standard (S) 

Unused (2 bytes) 
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ID=EXTRDIDOTASK : 


(1) 
(2) 
(3) 
(4) 
(5) 


Workstation device number of task specified, or 
-1 if none (1 byte). 

Current user ID for task specified, or blank if 
none (3 bytes). 

Current user name for task specified, or blank 
if none (24 bytes). 

Type ('F', 'FS', 'B', 'BS') of task specified 
(see TASKTYPE) (2 bytes). 

18 bytes of binary zeros (reserved). 


ID=EXTRDIDTAPEVOL: 


(1) 


(2) 
(3) 


(4) 


(5) 
(6) 


(7) 
(8) 


Device address, or ~-1 if volume not mounted 
(1 byte). 

1 byte of binary zero (reserved). 

Density, BPI in binary: 556, 800 or 1600 
(2 bytes). 

Label type: ‘AL' (ANSI), ‘NL' (no label), ‘IL’ 
(IBM label), or blank if volume not mounted. 
(2 bytes). 

Usage--'SH' (shared), ‘'EX' (exclusive), or 
blank if not mounted. (2 bytes). 

Task identifier of tape mounter, or -1 if none 
(4 bytes). 

Current file sequence number (2 bytes). 

Six bytes of binary zeros (reserved). 


ID=EX[TRDIDDEVLIST: 


(1) 


(2) 
(3) 


Total number of devices for specified device 
class (1 byte). 

Number of device addresses supplied (1 byte). 
Device address list (1 byte for each device 
address) . 


ID=EXTRDIDDLPNAME : 


(1) 
(2) 
(3) 
(4) 
(5) 


(6) 
(7) 


(8) 


Bit map of devices on DLP (4 bytes) 

First device on DLP (2 bytes) 

Type of DLP (1 = 22V06-1, 2 = 22V06-2, 
3 = 22V06-3) (1 byte) 

Number of lines (RS-232) controllable by the 
DLP (1 byte) 

Microcode file status (X'00' if stopped, X'80' 
if loaded) (1 byte) 

Reserved for future use (3 bytes) 

Microcode file name (8 bytes, zero if not 
loaded) 

Microcode library name (8 bytes, zero if not 
laoded) 
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(9) Microcode volume name (6 bytes, zero if not 
loaded) 

(10) Reservation status of DLP (X'80' if reserved, 
X'00' if not reserved) 

(11) Task number of the task which reserved the DLP 
(3 bytes) 


ID=EXTRDIDDLPDEV# : 


(1) Device status flag (X'80' if open, X'40' if 
reserved, zero otherwise) 

(2) Task number of the task which reserved the DLP, 
or zero if device is unreserved (3 bytes) 

(3) Name of the DLP on which the device is SYSGENed 
(4 bytes) 7 


ID=EXTRDIDCLUSTER : 

(1) Device number of the archiver driver, or zero 
(zero may indicate that there are no other 
devices on the cluster, or that among. the 
devices there is no archiver drive) 

(2) Unused (14 bytes) 

ID=EXTRDVOLVCB: 
(1) Volume Control Block address (4 bytes) 


Function: Extracts data from system control blocks which may be 
of interest to user programs. 
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Mount Disk Or Tape Volume 


MOUNT 


Input: 


(SVC 30) NONRESIDENT 


The input list is 8 bytes long, unless the high-order 
bit of the first byte in the Volume Name field (Bytes 
2-7) is set to 1, in which case the parameter list is 16 
bytes long. The parameter list on top of the _ stack 
contains: 


Byte 0 - Flags 


For disk mount, the flags are used as follows: 


- To mount an unlabelled volume. 
~ To mount a standard labelled volume. 
Bits 1-2 - Two bits used for volume usage description: 
=00 ~ Mount for shared use. 
=01 -— Mount with restricted removal. 
=10 - Mount with protected use, and restricted 
removal. 


=11 - Mount for exclusive use. 
Bit 3 = 1 - Mount a fixed volume. 
= 0 - Mount a removable volume. 
Bit 4 = 1 - 'No message’ option (see function below). 
Bit 5 = 1 - Mount volume for bypass-label-processing 


(see function below). 
Bit 6 = 1 ~ The volume to be mounted allows spool files. 
The volume to be mounted allows work files. 


7] 
fre 
cr 
~ 
il 
wy 
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For tape mount, the flags are used as follows: 


Bit 0 = 1 — To mount an unlabelled volume. 
= Q - To mount a standard labelled volume. 
Bit 1 = 1 - Volume mounted for exclusive use. 
= 0 - Volume mounted for shared use. 
Bit 2 = 1 - Unused. 
Bit 3 = 1 ~ Mount an IBM tape volume. 
= 0 - Mount an ANSI tape volume. 
Bit 4 = 1 - 'No message’ option (see function below). 
Bit 5 = 1- Mount volume for bypass~label-processing 
(see function below) . 
Bit 6-7. - (Unused). 


Byte 1 - Device number in binary (0-255). 


Bytes 2-7 - Volume name (if high-order bit is set to 1, 


then an 8-byte extension is added to the 
parameter list). 


MOUNT (SVC_ 30) 


Parameter List Extension 


Byte 8 


Bit 0 


1 - Non-standard addressing in effect (for 
soft-sectored diskettes only). 
Bit 1=1- 'No display option’: do not display message 
on user's workstation. 
Bits 2-7 - (Unused - must be zero) 


Bytes 9-15 - (Unused ~ must be zero) 


Outputs: 


Binary Return Code in the top word of the _ stack, 
replaces the input parameter. 


The following return codes are set when the new volume 
is physically mounted on the drive, and_ the 
corresponding VCB updated with the mounter TCB address, 
new volume label type, volume name and VTOC Block 
address (for labelled volume only). The sharing status 
('shared' or '‘exclusive') and the initialization status 
are updated as specified in he 'MOUNT' input parameter. 


Q ~- Success. 

4 - Successful mount, but new volume label type does 
not agree with input parameters 

8 - Successful mount, but new volume name is not the 
volume name requested 

12 - Disk or tape I/0 error detected while reading the 
new volume label or the new volume has a bad VTOC. 
VCBSER is set to blank. This return code is set 
when the new volume is physically mounted on the 
drive, but the VCB cannot be filled in. 


The following return codes are set without the mount 
message being shown on the workstation. The VCB for’ the 
volume is unchanged by the mount attempt. 


16 - Device is not a disk or a tape, or device number is 
invalid. 

20 ~ Device is detached. 

24 - Disk does not have the requested volume type (fixed 
or removable). 

28 - Request to mount an unlabelled volume on aé disk 
unit other than an 2270V diskette. 

32 - Input volume name is biank. 

36 - Requested volume is already mounted on a disk 
unit. Also set for a duplicate volume name. 

40 - Volume currently in use (by the operating system or 
user). 

44 - Currently mounted volume reserved by another user 
for exclusive use. 

48 - I/0 buffer space insufficient to perform mount. 

52 - Cannot allocate space for Tape I/O control blocks. 
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56 - Invalid request: work and/or spool filing requested 
in a non-labelled volume. 

60 - Invalid request: non-standard addressing attempted 
with standard label option or on aé_ hard-sectored 
device. 

64 - Wrong media: soft-sectored diskette inserted into 
a device for hard-sectored diskettes only. 

68 - Wrong media: hard-sectored diskette inserted into 
a device for soft-sectored diskettes only. 

72 - Wrong media: hard-sectored diskette inserted for a 
non-standard addressing request. 

76 - Wrong addressing mode: MOUNT request is for 
standard addressing but diskette is non-standard. 

80 - Device reserved by another user. 

84 MOUNT failed: aborted by user or operator request. 


Function: 


To mount a disk or tape volume. The input parameters are first 
validated, and if successful, a mount message will be displayed on 
the workstation to direct the user to mount the proper volume, 
unless the NODISPLAY option is chosen, in which case the message 
will appear only on the operator console. When the volume is 
mounted and the device is ready, the new volume label will then be 
read and checked, and the information in VCB is updated. 


The NO MESSAGE option indicates that the volume to be mounted is 
already on the drive. No mount message will be displayed, and the 
VCB information is updated from that volume label. 


The BYPASS-LABEL~PROCESSING option is used by the disk or tape 
initialization program and the floppy copy program (FLOPYDUP). At 
SVC EXIT, the VCB information is updated as follows: 


VCBSER is set to input bytes 2-7. 

VCB is set to be NOVTOC to allow non-labelled processing. 

VCB is set for exclusive use by the user. 

VCBFLAGSINIT = 1 to indicate that the VCB information could be 
inconsistent with the volume label. 


NOTE: 

A non-standard addressing option is now supported which allows the 
user to format a soft-sectored diskette in any combination of 
sector size and density. The use of this option is intended to be 
limited to specialized utilities. User programs which employ this 
option are responsible for performing direct and sequential I/O on 
a physical-sector basis. The user program must calcu~ late the 
sector size and addresses, set mode, and set density. When 
non-standard addressing is specified, the XIO SVC will not perform 
extent validation or address translation, but simply passes the 
address to the firmware via the 1/0 Control Word (IOCW). 
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Modify Program Exception Exit Status 


PCEXIT 


Inputs; 


(SVC 31) NONRESIDENT 


One or two words on stack top. The lower-addressed 
word contains class codes (0, 1 or 2 in binary) in its 
high-order byte. For class 0 only, the three low-order 
bytes of this word contain the specified exit address. 
The higher-addressed word, present for class 0 only, 
contains a bit map of exceptions for which the user 
exit is to be taken. 


Class codes are: 


0 - Establish new program exception exit address 
and conditions (exception list), saving the old 
status if any. 

1 - Restore previous program exception status, 
discarding current status. 

2- Cancel all program exception exits for the 
current program, discarding all status. 

The bit map of exceptions is as follows: 
Bit 0 - Unused 
~ Operation 
- Privileged Operation 
~- Execute 
Protection 
- Addressing 
- Specification 
~ Data 
~ Fixed Point Overflow 
~- Fixed Point Divide 
10 - Decimal Overflow 
11 - Decimal Divide 
12 ~ Supervisor Call Range 
13-15 - Unused 
16 - Floating Point Overflow 
17 - Floating Point Underflow 
18 ~- Significance 
19 - Floating Point Divide 
20-23 - Unused 
24 ~ Stack Overflow 
25-31 - Unused 


Wwrmownwt aw & whe S&S 
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Outputs: 


Function: 


Note: 


Program exception element(s) chained or removed from 
chain rooted in TCBPXE of the issuer's Task Control 
Block. Input parameters removed from stack. 


To modify the handling of program exceptions occurring 


in unprivileged user code, supplying or eliminating a 
current user exit address to receive control in the 
event of such an exception. 


When a program issues a LINK supervisor call, any 
current user program exception exit is eliminated, but 
the current status is preserved for restoration by 
UNLINK. (Execution of PCEXIT SVC Class 1 will not 
restore a program check exit status existing prior to a 
LINK.) 
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SETIME/RESETIME (SVC 32) NONRESIDENT 


Inputs: 


Outputs: 


Function: 


Word on top of stack. The high-order byte of the 
lower-addressed word contains a class code in binary as 
follows: 


X'40' - Set timing interval to expire at time of day 
specified in the three low-order bytes of 
parameter word, where this time is in 1/100 
seconds into a day, from midnight. To request 
expiration at some time tomorrow, the value 
supplied must be 24 hours plus the required 
time of day. A requested time less than the 
current time of day will result in immediate 
expiration. 


X'00' - Set times interval to expire after the number 
of 1/100 second units in the three low-order 
bytes of parameter word have elapsed. 


X'80' ~- Remove timing interval previously established 
' (can require removal of a TQEL from the time 
queue) . 


A Timing Queue Element (TQEL) is placed in 
time-sequenced order on the timing queue (from MCBTIMQ) 
or is removed from that queue. The clock comparator 
value is modified if required. The input word is 
removed from the stack. The issuing task continues. 


To establish a timer interval, which may then be 


awaited by means of the CHECK supervisor call, or to 
remove an unCHECKED interval. 
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PUTPARM (SVC 33) Non-Resident 


Inputs: The top 28 bytes of the stack contain the parameter 
list as follows: 


Byte 0: Flags 


Bit 0 = 1 DISPLAY option 
= 0 ENTER option 
Bit 1=1 REFER option 
Bit 2=1 CLEANUP option 
Bit 3 = 1 MERGE option 
= 0 NOMERGE option 
Bit 4=1 Enable Repeat Count 
Bit 5 =1 CLEANUP labelled FMTLIST (Bit 2 must 
| also be set) 
Bits 6-7 Reserved, must be zero 
Byte 1: The AID character of a PFkey to be passed to 


the GETPARM if this is a backward reference; 
otherwise, not used and must be zero. 


Bytes 2-3: Repeat count as follows (if flag bit 4 is 


on): 
Xx'0000' Never repeat 
X'1'-X'7FFF' Repeat n times 
X'8000' Repeat indefinitely 


If flag bit 4 is off, field is not used and 
must be zero. 


Bytes 4-11: If REFER NOMERGE or labeled CLEANUP option, 
bytes 4-11 contain the label of the FMTLIST 
to be referenced. If REFERLABEL is used in 
PUT option, bytes 4-11 contain the 
REFERLABEL. For unlabelled CLEANUP option, 
bytes 4-11 are all blanks. Otherwise, byte 
4 must be zero, bytes 5-7 contain the 
address of the supplied FMTLIST (the 
destination FMTLIST for the REFER MERGE 
option), and bytes 8-11 are unused and must 
be zero. 


Bytes 12-19: The PRNAME to be associated with the 


FMTLIST. 
Bytes 20-27: The label of the FMTLIST to be created or 
accessed. Blanks indicate that no label is 


specified. If the MERGE or MERGE,REMOVE 
option is being used, bytes 20-27 contain 
the label of the source FMTLIST. 
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Outputs: 


PUTPARM returns to the issuer eight bytes on the 
top of the stack: 


Bytes 0-3: Return Code: 

0 -~- £Successful. 

4 - Backward reference label not 
found. 

8 - Bad FMTLIST supplied. 

12 - Error found in previously 
constructed Parameter 
Reference Blocks (PRBs). 

16 - Invalid input parameter 
while using CLEANUP option. 

20 ~ Invalid input parameter 


while using MERGE option. 


Bytes 4-7; If Return Code is 0, address of 
FMTLIST specified in the input or 
backward referenced. 


Function: The PUTPARM SVC has three major functions. The primary 


PUT 


function (PUT function) is to supply parameters. to 
another program's GETPARMs before issuing the LINK SVC 
to invoke. The second function (the CLEANUP function) 
is to cleanup the various internal data structures 
created by the PUT function. The third function (the 
REFER function) is to allow the calling program access 
to any parameters which the user may have changed at 
GETPARM time (the MERGE option), or to return the 
address of a previously created and labelled fFMTLIST 
(the NOMERGE option). | 


Both the PUTPARM macro and the LINKPARM macro call the 
PUTPARM SVC. The PUITPARM macro allows only the 
parameterization of another program (the PUT function), 
while the LINKPARM macro accesses all the functions of 
the PUTPARM SVC. 


PUTPARM's primary use is to enable a program to supply 
parameters to a GETPARM issued by another program (the 
PUT function). The program supplying the parameters 
must link to the program issuing the GETPARM via_ the 
LINK SVC. A program may not use PUTPARM to pass 
parameters to its own GETPARMs. 
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The parameters to be supplied to the GETPARM are 
contained in a format list (FMTLIST), created with the 
FMTLIST macroinstruction. (A FMTLIST is identical to a 
KEYLIST, except that a FMTLIST contains no PRNAME.) 
When a PUTPARM is issued, it verifies that the specified 
FMTLIST is in the proper format, then saves the FMTLIST 
in a segment 2 buffer for subsequent GETPARM use. 
PUTPARM also constructs a Parameter Reference Block 
(PRB) to save the label, PRNAME, display option, and 
certain other information. The PRB is constructed in 
the segment 2 buffer area allocated by the PUTPARM SVC 
and chained to the previously constructed PRBs. 


When a GETPARM in the linked-to program is issued, it 
searches through the current link level's saved (and 
unused) PRBs for one whose PRNAME matches the PRNAME of 
the GETPARM's KEYLIST. If one is found, the value for 
the keywords in the FMTLIST will be copied to _ the 
GETPARM KEYLIST (left-aligned and truncated). To 
solicit modifications by the user, A GETPARM workstation 
transaction may be requested by selecting the DISPLAY 
option; otherwise, a workstation transaction is 
suppressed. The KEYLIST (possibly modified by the user) 
is merged back into the FMTLIST for later backward 
reference. 


If more than one GETPARM is issued with the same PRNAME, 
the PUTPARM-saved FMTLISTs will be used in the order in 
which they were supplied to the PUTPARM SVC. Normally, 
no two GETPARM requests access the same FMTLIST. A 
FMILIST may be declared to be for repeated use via the 
Macro parameter REPEAT=. 


A FMTLIST may be labeled (via the LABEL= parameter) for 
later use. The backward reference facility allows a 
program to reuse the (possibly updated) parameters of a 
labeled fFMTILIST. If a backward reference label is 
supplied to the PUTPARM SVC rather than a FMTLIST (e.g., 
via the REFERLABEL= parameter of the LINKPARM macro), a 
pointer to the labeled FMTLIST will be stored thus 
causing GETPARM to reuse the labled FMTLIST. 


As an example of the backward reference facility, 
suppose that the program being parameterized requests 
the same set of parameters several times and that the 
calling program is suppressing the workstation trans- 
actions. The calling program could issue LINKPARM PUT 
several times, each specifying fully the GETPARM 
parameters. If one of the parameters was in error, the 
user would be forced to correct each transaction. If 
instead, only the first LINKPARM PUT specified the 
parameters (and was labeled) and the others referred 
back to the first, the user would only have to correct 
the first transaction. 
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CLEANUP 


The PUTPARM SVC also supports an override facility. If 
the PRNAME specified by the linking program matches the 
LABEL of a FMTLIST specified by the linked-to program, 
the parameter values in the linking program's FMTLIST 
will override those of the linked-to program's FMTLIST. 
Parameters not specified by the linking program retain 
the values specified by the linked-to program. 


For example, suppose program 1 issues the following 
LINKPARM (FMTL1 sets KEY2 to 'PROG1'): 


LINKPARM PUT, PRNAME=' OVERRIDE‘ , FMTLIST=FMTL1 


and then links to program 2. Now suppose that program 2 
issues the following LINKPARM (FMTL2 sets KEY1 and KEY2 
to 'PROG2'): 


LINKPARM PUT ,PRNAME='DEMO‘' ,LABEL='OVERRIDE', 
FMTLIST=FMTL2 


and then links to program 3. A GETPARM for PRNAME 
"DEMO' by program 3 will set KEY] to 'PROG2' and KEY2 to 
"PROG1'. 


As well as passing parameters to GETPARMs, PUTPARM may 
also pass a PFkey. This may be done in one of two ways, 
via either the PFKEY= or AID= parameter. Both can pass 
the full range of 32 PFkeys plus ENTER. PFKEY= takes 
either the actual key number (1-32) or the keyword 
ENTER. AID= takes the '‘'AID' character of the PFkey, 
where 'A'-'P' correspond to PFkeys 1-16 respectively, 
"a'-'p' correspond to PFkeys 17-32 respectively, and @ 
corresponds to the ENTER key. Both methods have the 
same result (PFKEY= values are translated into AID= 
values for the SVC by the macro). The way in which the 
PFkey is passed to GETPARM depends on whether the 
LINKPARM is a normal or a backward reference. 


In the normal case, the PFkey is placed into the first 
byte of the FMILIST addressed by FMTLIST= by the 
LINKPARM macro. Note that the original FMTLIST is 
modified. In the case of a backward reference, the 
PFkey is placed onto the stack and then into the FMTLIST 
buffer. The original FMTLIST is not modified in this 
case. 


The CLEANUP option is used to deallocate all the PRBs 
(and their associated FMTLISTs) chained to the Program 
File Block (PFB) of the current link level and above. 
This option enables the user to free the segment 2 
buffers allocated for PUTPARM use. If no REFERLABEL is 
provided on the call, all PRBs and FMTLISTs at the 
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current link level and above are removed. If a 
REFERLABEL is provided, only the PRB and associated 
FMTLIST referenced by REFERLABEL is removed. The 
CLEANUP option may be used concurrently with the REFER 
option via specification of the REFER,REMOVE option in 
the LINKPARM macro (see below). The CLEANUP function is 
useful for programs which loop executing a large number 
of LINKPARMs to prevent FMTLIST buffers from becoming 
full. 


The REFER ,NOMERGE function of the PUTPARM SVC is to 
return the address (in the segment 2 buffer) of a 
previously created and labeled FMTLIST without the 
overhead of creating a new FMTLIST or a_ reference 
pointer. This function is used primarily by the 
Procedure Interpreter. 


This feature is used primarily by programs which desire 
to keep track of any GETPARM parameters which a user 
might have overridden. This option allows the user of 
the LINKPARM macro to specify both a FMTLIST and a 
REFERLABEL. The contents of the FMTLIST addressed by 
the REFERLABEL= (the source) are merged into the FMTLIST 
addressed by FMTLIST= (the destination). Fields which 
are present in the destination but not the source are 
left unchanged. Fields which are present in the source 
but not the destination are ignored. The MERGE option 
may be combined with the CLEANUP option (the MERGE 
option is performed first) via the REMOVE operand. 
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Set Task-Related Defaults 


SET 


Inputs: 


A variable-length parameter list on the 


must have 


(SVC 35) NONRESIDENT 


stack top, 
consisting entirely of address pointers or words 
containing binary zeros. The last word of the list 
its highest bit on (‘'1'). Nonzero words 
address data items which replace corresponding task 
defaults as follows: 


Index of Parameter Length Corresponding 
List Address Default of Item Procedure Keyword 

0 ETCBLINKVOL 6 PROGVOL 
4 ETCBLINKNAME 8 PROGLIB 
8 unused = = 
12 ETCBDEFVOL 6 INVOL 
16 ETCBDEFFILE1 8 INLIB 
20 unused 5 ze 
24 ETCBDEFVOLO 6 OUTVOL 
28 ETCBDEFFILE10 8 OUTLIB 
32 ETCBDEFVOLS 6 SPOOLVOL 
36 ETCBDEFVOLW 6 WORKVOL 
40 ETCBDEFPRT 1 PRINTER 
44 ETCBPRTITYPE 1 PRNIMODE 
48 ETCBFPCLASS 1 FILECLAS 
52 ETCBLINEAGE 1 LINES 
56 ETCBPRTCLASS 1 PRTCLAS 
60 ETCBFORMNO 1 FORM# 
64 ETCBUPDVOL 6 RUNVOL 
68 ETCBUPDNAME 8 RUNLIB 
72 ETCBJOBSTATUS 1 JOBQUEUE 
76 ETCBJOBCLASS 1 JOBCLASS 
80 ETCBJOBLIMIT 4 JOBLIMIT 

Outputs: The task's Extended Task Control Block is modified as 
requested. The parameter list is removed from the 
stack. 

Function: To allow programs (especially the system's Procedure 


Interpreter) to modify default values. Most of these 
can also be modified by means of the ‘SET’ command. 


Fields ETCBLINKVOL or ETCBLINKNAME modified by means of 


this SVC routine will be restored to their previous 
values when the issuing program UNLINKs. 
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Transmit Intertask Message 


XMIT SVC 36 RESIDENT 


Inputs: Two words on top of the stack as follows: 


i 
=) 


Byte 0, Bit 0 Wait if not enough buffer space. 

. 1 NOWAIT option, return if not 
enough buffer space. 

1= 0 OTHERTASK option, transmit only 


to other tasks. 


2-7 = 0 (Reserved) 
Bytes 1-3 Address of a message to be 
transmitted. 
Bytes 4-7 Name (any characters) of receipt 


port for messages. 


Outputs: The supplied message is placed in a system message 
buffer. This is copied to the address specified by the 
receiver as a result of the CHECK SVC routine with the 
MESSAGE option. The first two bytes of the supplied 
message indicate its length, including those bytes, and 
must be not greater than 2016. 


Return codes are placed in a word on the stack. top, 
replacing the inputs: 


0 - Successful. 

4 - No receiving port with the specified name. 

8 - Unable to insert message in receiving port's 
message buffer -- insufficient remaining space 
in message buffer (NOWAIT option only). 

12 - Unable to insert message in receiving port's 
message buffer due to receiving port's use of 
PRIVILEGED option. 

16 ~- Message not transmitted; OTHERTASK option was 
specified and the designated message port 


belongs to the XMIT-issuing task. 


Function: To communicate between user tasks, or between a user 
task and a specific subsystem of the operating system. 
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CREATE (SVC 37) NONRESIDENT 


Inputs: Two words on top of stack, as follows. 


Byte 0, Bit 0 = 0O Receive all messages. 
1 Privileged Option. 
1-7 = 0 (Reserved) 

Byte 1 Reserved (X'0'). 

Bytes 2-3 Space to be allocated in buffer 
to receive messages (not greater 
than 2016). 

Bytes 4-7 Name (any characters) of receipt 


port for messages. 


Outputs: Resident buffer with specified name created to receive 
intertask messages. 


Return codes are placed in a word on the stack top, 
replacing the inputs. 


0- 


4 - 


12: 


Function: Allows 
sent by 


Successful. 


Another task has activated the specified port 
name. 


Same task has already activated the specified 
port name. 


GETMEM failure. 


the issuing task to receive intertask messages 
XMIT (SVC 36) to the specified port name, 


rejecting any messages from non-privileged state code 


or from 


tasks that are not dedicated system tasks if 


the port was created with the PRIVILEGED option. 
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Destroy Intertask Message Buffer 


DESTROY (SVC 38) NONRESIDENT 


Inputs: 


Outputs: 


One word on top of stack, containing name of one of 
this issuer's message receipt ports. 


The message buffer associated with the specified name 
is eliminated. If no such message buffer has been 
CREATEd by this task, the issuer is informed by a 
return code. 


Return codes are placed in a word on the stack top, 
replacing the inputs: 


0 - Successful. 


4 - One or more messages were not received and are 
lost; otherwise successful. 


8 -~ No such message buffer was allocated by this 
task. 


Function: To remove from the issuing task the ability to receive 


messages directed to the specified name. 
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Set Cancel Exit Options 


CEXIT 


Inputs: 


Outputs: 


(SVC 39) NONRESIDENT 


One or three words on stack top. For the CANCEL 
option, a word of binary zeros is on the. stack. 
Otherwise, three words of the following format: 


Byte 0 Flags 
Bit O = 1 SET Option. 
Bits 1-2 = 00 Debug enabled. 
= 01 NODEBUG Option. 
= 11 DUMP option. 
Bit 3 0 HELP Key enabled. 


1 HELP Key disabled. 


Bytes 1-3 Address of User Cancel Exit Intercept 
Routine, or zero. 


Bytes 4-7 Address of User-Supplied Message to be used 
in place of the "CANCEL PROCESSING" Menu 
descriptions, or zero. 


Bytes 8-11 Reserved (must be zero). 


PFB updated with CEXIT options as specified with 
parameters. Input parameters removed from _ stack. 
Abnormal termination occurs if either an invalid Cancel 
Intercept Address is provided (Message 0001 by SVC39) 
or an invalid Cancel Menu Message Mask Address is 
provided (Message 0002 by SVC39). 


Function: To set CEXIT options in the current link level PFB. 
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Dismount Disk or Tape Volume 


DISMOUNT (SVC 41) NONRESIDENT 


Inputs: 8 bytes on top of stack: 


Byte 0 
Bit 0 = 0 
= 1 
Bit 1 =1 
Bits 2-7 
Byte 1 
Bytes 2 - 7 


-~ Dismount disk volume. 

-- Dismount tape volume. 

-- No display option: do not write to 
caller's workstation. 

-- Reserved; must be zero. 


-~- Reserved; must be zero. 


-~ Volume name. 


Outputs: 4 bytes of Return Code on stack top, replacing input: 


0 
4 


8 

12 
16 
20 
24 
28 
32 


Succes 
Input 

input 

Volume 
Volume 
Device 
Volume 
Volume 
GETMEM 
Device 


sful 
volume name is blank, or bytes O-1 in 
are nonzero 

not found 

not dismountable 

detached 

in use by a user or the operating system 
reserved by another user 

failure 

is reserved by another task 


Function: To perform disk and tape dismount operations for the 
volume specified in the input. 


6-73 


Protect File or Library 


PROTECT (SVC 42) NONRESIDENT 


Inputs: The top word of the stack addresses an argument list of 
the following format: 


| New Expiration Date | 3 Bytes 
| or Retention Period 
| New ID of Owner | 3 Byte 
| New Protection Class | 1 Byte 
| Option Flag | 1 Byte 
| Volume Serial | 6 Bytes 
| File Name or Ignored | 8 Bytes 
Argument List | Library Name | 8 Bytes 


The Option Flag indicates which protection data is to 
be changed and whether to protect a file or a full 
library: 


= '1' To Set Owner ID 


‘1' To Set Protection Class 


‘1' If Expiration Date Supplied 
(YYDDD+) 


‘1' If Retention Period Supplied 
(OODDD+) 


‘1' If File Access Rights are to be limited 
to User Logon Rights 


‘1' To Protect a Library 


Bits O and 3 should have values of 0. 
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Outputs: 


Function: 


PROTECT (SVC 42) 


The protection attributes for the file or library 


identified 
top word of 


Return 


Return 
Return 
Return 


Return 
Return 
Return 


Return 
Return 
Return 
Return 
Return 
Return 
Return 


Return 


Code 


Code 
Code 
Code 


Code 
Code 
Code 


Code 
Code 
Code 
Code 
Code 
Code 
Code 


Code 


is modified. Return codes in binary in the 
the stack indicate the result of the request: 


To update the 


by the change. 


56 


Protection status successfully 
changed 

Volume not mounted 

Volume used exclusively by other user 
All buffers in use, no protection 
change 

Library not found 

File not found 

Update access denied, no protection 
change 

Unused 

File in use, no protection change 
VTOC error! FDX1 & FDX2 don't agree 
VTOC error! FDX2 & FDR don't agree 
Invalid argument list address 

1/0 error! VTOC unreliable! 

Open or protected files bypassed in 
protecting library 

Invalid new protection data 


protection information (protection class, 
owner of record, and/or expiration date) for a disk file 
or a library of disk files on a volume. The structure 
of the Volume Table of Contents (VTOC) is not affected — 
No file that is to have its protection 
information modified may be open when the PROTECT is 
attempted. 
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Log Off Interactive Terminal 


LOGOFF 


Inputs: 


Outputs: 


(SVC 43) NONRESIDENT 


Two words on stack top. These words are reserved for 
future use and currently must contain binary zeroes. 


PFB updated with the CEXIT option of NODEBUG and the 
logoff flag in the ETCB is set (ETICBFLGLOGOFF) for 
subsequent inspection by the appropriate Command 
Processor routines. A CANCEL SVC is issued with Message 
0001 by SsvVC43. If the input parameter words are not 
binary zeroes, a CANCEL SVC is issued (Message 0002 by 
SVC43) and the logoff flag bit is not set, 


Function: To effect logoff by program request. 
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Submit Job or Print Request 


SUBMIT (SVC 46) 


NONRESIDENT 


INPUTS: Accepts a parameter list of one word on the stack top: 


Byte 0: 


Bytes 1-3: 


Operation (Binary value, 1-255) 


=] Submit job for processing. 
=2 Request printing of print file. 


Address of a 44-byte parameter list 
(word-aligned) for the operation. 


Operation: Submit Job for Processing 


Parameter List Format: 


Bytes 0-7 
8-15 
16-21 
22-29 
30 
31 


32-35 


36 


37 


38-43 


Procedure name 

Library name 

Volume name 

Job name or blanks (optional) 

Job class (A-Z) 

DUMP options: 

X'80' User has specified DUMP or NODUMP on 

CANCEL (ETCBBGDUMPOPT) 

X'40' Force DUMP on CANCEL (ETCBBGDUMP) 

CPU time limit in timer units; if zero is 

supplied, then there is no time limit. 
Initial status of job when queued: 
X'80' Hold Not eligible for scheduling 
until released by the 
operator or submitter. 
X'00' Active Eligible for scheduling upon 
submission of the request. 
X'80' Test for time limit up -- must be 
set of a time limit is specified 
(TCBTIMLIMCHK) . 

X'40' Force CANCEL if limit is up 
(TCBTIMLIMCNCL) . 

X'20' Force Pause/HELP if limit is up 
(TCBTIMLIMPAUSE) . 


(If neither TCBTIMLIMCNCL nor 
TCBTIMLIMPAUSE is set and a CPU time limit 
is set, then a warning will be issued.) 


X'04' Disposition after job processing: 
Requeue after execution. 


Reserved (should be zeros). 
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SUBMIT (SVC 46) 


Outputs: A return code is returned in the stack top word, with 
the following meaning: 


48 


52 
56 


Successful 

Volume not mounted 

Volume in exclusive use 

All buffers in use -- unable to perform 
verification 

Library not found 

File not found 

Improper file type (or zero records as 
indicated in FDRINRECS). 

File access denied 

VTOC error, FDX1 and FDX2 do not agree 

VTOC error, FDX2 and FDR do not agree 

Invalid specification of file, library, and 
volume 

System task not running, no spooled printing or 
interactive jobs 

Error in performing XMIT to System task 

Invalid options specified in parameter list 


Operation: Request Printing of Print File 


Parameter List Format: 


Bytes 


0-7 Print file name 
8-15 Library name 
16-21 Volume name 


22 Print class (A-Z) 

23 Form # in binary (0-255) 

24-25 Number of copies in binary 

26 Initial status of this file when queued: 


X'80' Hold Not eligible for print 
scheduling until released by 
the operator or the 
submitter. 

X'00' Spool Eligible for printing upon 
submission of the request. 

27 Disposition after printing: 

X'40* - Requeue after print 

x'20' - Save after printing 

X'02' - Collective print 

28-43 Reserved (should be zero) 


Outputs: A return code is returned in the stack top word with 
the same meaning as above for the SUBMIT job processing 
function. 
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Allocate Heap Storage 


GETHEAP (SVC 56) NONRESIDENT 


Inputs: The top 16 bytes of the stack contain a parameter list 
as follows: 


Byte 0: Option flags: 


Bit 0 =1 SEARCH flag. Search backward for the 
subpool name specified in the 'POOLNAME' 
parameter of the GETHEAP macro (Bytes 8-15 
of this input parameter list), starting 
from the link level specified in the 
"LINKLEV' parameter of the GETHEAP macro 
(Byte 4 of this input parameter list) and 
going backwards until the subpool is found 
or all the link levels are exhausted. 


=0 Search only at the link level specified in 
the 'LINKLEV' parameter of the GETHEAP 
macro (Byte 4 of this input parameter list). 


Bit 1 =1 CREATE flag. Create a new subpool with the 
name specified in the 'POOLNAME’ parameter 
of the GETHEAP macro (Bytes 8-15 of this 
input parameter list) and at the link level 
specified in the 'LINKLEV' parameter of the 
GETHEAP macro (Byte 4 of this input 
parameter list). A backward search is 
never initiated if the CREATE flag is set, 
and the SEARCH flag, if specified, is 
ignored. 


Bit 2 =1 ALIGN flag. A 2K-aligned block is 
requested by the user. Useful only when a 
multiple of 2K bytes is requested; ignored 
otherwise. 


Bits 3-7 Reserved; must be zero. 


Bytes 1-3: SIZE Size of the block. All sizes are 
allowed, but they will be rounded up to 
their nearest 8-byte multiple. 


Byte 4:3 LINKLEV Link level from which to start 
searching for the subpool. ‘O' means 
the current link level, ‘1 its parent, 
and so on. A value of 255 (X'FF') in 
this field represents the lowermost 
link level. 


Bytes 57/7: Reserved; must be zero. 
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GETHEAP (SVC 56) 


Bytes 8-15: POOLNAME 8-byte character string 


Outputs: 


12 


20 


24 


28 


representing the subpool name. Blank names are 
not allowed. Trailing blanks are insignificant. 


A return code is returned in the stack top word. If 
Return Code = 0, the next word in the stack contains the 
Starting address of the block; if Return Code = 4, the 
next word in the stack contains the size of the largest 
block available. Return codes have the _ following 
meanings: 


A buffer area has been allocated. The next word on 
the stack contains the block starting address. If 
requested, a subpool has also been created. 


- Not enough space in segment 2. The next word on the 
stack contains the size of the largest block 
available. If requested, a subpool has also been 
created. 


~ Nonexistent link level specified. 
- Nonexistent subpool name specified. 


- User has overwritten area used by GETHEAP. User 
should CANCEL at this point. 


- Error in parameter list. 'POOLNAME' all blank or a 
nonzero value in reserved fields. 


- GETMEM failure. A new subpool cannot be created. 
This however does not prevent the user from 
allocating space from an existing subpool. 


~- CREATE failure. A subpool with the same name 
already exists at this link level. 


Function: To allocate a block as requested. All block sizes 


including zero are legal. If, however, the block size 
is not a multiple of 8 bytes, the size is rounded up to 
the nearest 8-byte multiple. Maximum size is restricted 
only by the caller's segment 2 size less the size used 
by the system stack. The space is taken from the _ low 
end of segment 2. The value in control register 2 may 
be modified. Both the creation of a new subpool and 
allocation of a block out of the subpool can be 
accomplished in a single GETHEAP call. Successful 
creation of a subpool does not guarantee that a block of 
proper size can be allocated. There is no fixed space 
associated with the creation of a subpool; the space is 
allocated as and when requested. 
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Deallocate Heap Storage 


FREEHEAP (SVC 57) 


NONRESIDENT 


Inputs: The top 16 bytes of the stack contain a parameter list 


as follows: 
Byte 0: 


Bit 0 


Bit 1 


Bits 


Bytes 1-3: 


Byte 4: 


Bytes 5-7: 


Option flags: 


=1 SEARCH flag. Search backward for the 


2-7 


SIZE 


subpool name specified in the 
*POOLNAME' parameter of the FREEHEAP 
macro (Bytes 8-15 of this input 
parameter list), starting from the 
link level specified in the 'LINKLEV' 
parameter of the FREEHEAP macro (Byte 
4 of this input parameter list) and 
going backwards until the subpool is 
found or all the link levels are 
exhausted. 


Search only = at the link level 
specified in the ‘LINKLEV' parameter 
of the FREEHEAP macro (Byte 4 of this 
input parameter list). 


DELETE flag. Delete an entire subpool 
with the name specified in the 
*POOLNAME' parameter of the FREEHEAP 
macro (Bytes 8-15 of this input 
parameter list) and at the link level 
specified in the '‘LINKLEV' parameter 
of the FREEHEAP macro (Byte 4 of this 
input parameter list). A backward 
search is never initiated if the 
DELETE flag is set, and the SEARCH 
flag, if specified, is ignored. 


Reserved; must be zero. 
Size of the block. All sizes are 


allowed, but they will be rounded up 
to their nearest 8-byte multiple. 


LINKLEV Link level from which to start 


searching for the subpool. ‘0’ means 
the current link level, ‘1' its 
parent, and so on. A value of 255 
(X'FF') in this field represents the 
lowermost link level. 


BUFLOC Starting address of the block to be 


deleted. 
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FREEHEAP (SVC 57) 


Outputs: 


Function: 


Bytes 8-15: POOLNAME 8-byte character string 
representing the subpool name. Blank 
names are not allowed. Trailing 


blanks are insignificant. 


When the deletion of an entire subpool is desired, the 
SIZE and BUFLOC parameters have no meaning and are 
ignored. 


A return code on the top word of the system stack with 
the following meaning: 


QO - A buffer area has been deallocated or an entire 
subpool has been deleted. 


4 - Invalid buffer address specified. 

8 - Nonexistent link level specified. 

12 - Nonexistent subpool name specified. 

16 - User has overwritten area used by FREEHEAP. 


User should CANCEL at this point. 


20 - Error in parameter list. ‘'POOLNAME' all blank 
or nonzero value in reserved fields. 


To de-allocate a block as requested. All block sizes, 
including zero, are legal, but they will be rounded up 
to their nearest 8-byte multiple. An entire subpool 
can also be deleted in a single FREEHEAP call, through 
the use of the DELETE flag. The value in control 
register 2 may be modified. 


On UNLINK, all the subpools belonging to that link 
level are automatically deleted. 


6-82 


CHAPTER 7: DATA MANAGEMENT SYSTEM SERVICES 


7.1 INTRODUCTION 


The Data Management System (DMS) is described from the user 
program viewpoint in this section. The user program communicates 
with DMS routines through the User File Block (UFB). A user 
program has one UFB for each file it can process. When a UFB is 
connected to an OFB by SVC OPEN, the file is considered OPEN and 
may be processed through function requests to the Data Management 
System using the UFB. The system enforces a limit on the number 
of files a user program can have OPEN at any one time. A file is 
removed from the OPEN state by using SVC CLOSE. A user program's 
UFBs are located in the user's modifiable data area (Segment 2). 
SVC 0 (OPEN) and SVC 1 (CLOSE) are described in Chapter 6. 


DMS function-routines are reentrant routines and are located as 
part of the system code (Segment 0). They execute in User State 
and use SVCs (XIO, CHECK, ALEX, UPDATFDR, DTI) to perform 
privileged I/0 operations and to modify protected control blocks 
(OFB, FLUB, etc.). DMS function-routines can be used by multiple 
users; they perform as if they were an extension of the _ user 
program. 


The UFB is logically divided into four sections as follows: 


a. Access Method Section - This section contains some 
basic infomnation used by the DMS function-routines. 


i. Five function vectors, corresponding to the five 
function-requests allowed ona file. A function 
vector consists of a modifier byte and_ the 
address of a DMS function-routine (loaded by 
OPEN). 


ii. Two user-supplied function-routine error~exit 
addresses. 


iii. The record-area pointer (user supplied). 


iv. The key-area pointer (user supplied). 
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v. Two File Status Bytes (UFBFS1 and UFBFS2) used to 
returm an ASCII-character code to the user for 
each function-request. 


File Location and Attributes Section - This section 
contains various information (assembled by SVC OPEN) 
about the file. 


Data Management System Section - This section contains 
an Open File Block (OFB) pointer for the file, 
buffer-related information (including two Buffer control 
Blocks), and other data used by the Data Management 
System. 


Indexed Disk File Extension - This Section is present 
for indexed disk files only; it contains information 
regarding the file index, etc. 


7.2 VS DISK FILES 


This sect 
methods 
does not 
a. 
b. 
Ce 
There are 
System: 
1. 
2. 
ae 
The VS 
such as: 
a. 
b. 
Ci 
d. 


ion describes the DMS functions, open-modes, and access 
for disk files residing on a disk volume with a VTOC. DMS 
distinguish between disk volumes and diskette volumes. 


A disk file resides on a disk volume. A disk file is 
fully contained within a disk volume (a file cannot span 
a volume). 


Each file has an associated file label in the VTOC. 
File label format is described by the FDR1 and FDR2 
control blocks. 


The physical block size for a disk file is 2048 bytes. 


Records in a disk file are always blocked (in 2K 
physical blocks). 


three access methods supported by the VS Data Management 
Record Access Method (RAM). 


Block Access Method (BAM). 
Physical Access Method (PAM). 


DMS access methods are characterized by several factors 
unit of data transfer. 
buffer support; blocking and deblocking support by DMS. 


physical 1/0 support provided by DMS. 
file-organization dependence. 


T=2 


The following pages within this section describe each of these 
access methods in detail for disk devices and disk files. Other 
files (on other devices) are also processed under one or more of 
the access methods. The other devices are described separately. 


The pages at the end of this section (Notes on VS Disk Files) 
describe certain specific UFB and FDR (file label) fields that 
may be of interest to the assembly language programmer. Other 
topics such as NOVTOC diskettes are also noted. 


7.2.1 Record Access Method (RAM) - Disk Files 


The unit of data transfer is the logical record as indicated in 
UFBRECSIZE. This Access Method is the normal (default) access 
method assigned by SVC OPEN. Files are accessed ina file 
organization dependent manner. This access method includes: 


a. random and sequential access of consecutive files 
(fixed length or variable length records). 


b. sequential and keyed access of consecutive files (data 
records). 


c. indexed file sequential creation. 
d. sharing files for update. 
Open Modes supported under RAM © 


a. Output mode - This mode supports the creation of a 
file. Records are presented by the user program in 
sequential order. For indexed files, each record must 
have a greater key value than the preceding record. 
The WRITE function request causes the record from the 
user-record-area to be the last record in the file. 


The following modes are used with existing files. 


b. Input mode - This mode supports the retrieval of 
records froma file. Records may be read (randon, 
sequential or keyed) but may not be modified. Multiple 
user~programs can access the same file in Input mode 
since no modification is allowed. The READ function 
request causes a record from the file to be read into 
the user-record-area. 
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Input/Output mode (1/0 mode) - This mode supports 
retrieval and modification of records in a file. Only 
one user-program (at a time) can access a particular 
file in I/O mode. The REWRITE function request is 
available to rewrite the (updated) record from the 
user-record-area to the file. The REWRITE function 
request accesses the last record read from the file by 
the program; REWRITE must be preceded by a READ(HOLD) 
function request. If the file is an indexed file, 
records may also be added (keyed, WRITE) or removed 
(DELETE) from the file in I/O mode. 


Extend mode - This mode supports the addition of new 
records to the end of an existing disk file. Only one 
user program (at a time) can access a particular file 
in Extend mode. SVC OPEN positions the logical record 
pointer so that all WRITE function-requests add records 
to the end of the file. Extend mode is valid for 
consecutive files only (for indexed files, I/O mode 
provides the ability to add records to the files). 


Shared mode - This mode supports all the functions 
supported in I/O mode except READ NODATA. However, 
shared mode also provides an update~interlock system 
which allows multiple user-programs to update the same 
file concurrently. DMS grants exclusive control of a' 
record to a program to insure that concurrent file 
updates are processed correctly. DMS provides all 
shared file support. 


FUNCTION REQUESTS PROVIDED FOR DISK FILES UNDER THE DMS RECORD 
ACCESS METHOD 


FILE ORGANIZATION - CONSECUTIVE 
RECORD FORMAT - FIXED LENGTH RECORDS 


| Input | Output | 1/0 | Extend | Shared 


| | 
| Read | x | | x | | 
| Write | | xX | | xX | | 
| Rewrite | | i x | | | 
| Start | | x | | xX | | 
| Delete | | | | | 


FILE ORGANIZATION ~ INDEXED 
RECORD FORMAT - FIXED LENGTH RECORDS 


| Input | Output | 1/0 | Extend | Shared 


| | 
| Read | x | | x | | xX | 
| Write | | Xx | xX | | xX | 
| Rewrite | | x | | X | 
| Start 1 x | } x | | D4 | 
| Delete | | | x | | xX | 


FILE ORGANIZATION - CONSECUTIVE 
RECORD FORMAT - VARIABLE-LENGTH RECORDS* 


| Input | Output | I/O | Extend | Shared 


| | 

| Read | x | | x | | | 

| Write | | x. | X | xX | 

| Rewrite | | {| x | | 

{| Start | x | a oe | x | | 

| Delete | | | | | | 
* Shared mode is supported for consecutive log files. (A 


consecutive log file must have variable-length records.) 
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File Organization Definitions 


Consecutive Disk File 
Fixed Length Records (Blocked) 


Disk Block (2K) 
| Record 1 | Record 2 | Record 3 | Record 4 | /// | 


The fixed-length records are blocked; block size is 2048. Each 
block in the file except (possibly) the last block contains the 
same number of records. Records do not span blocks. A 2K disk 
block contains unused space at the end if the record size is not 
an even divisor of 2K. 


Record Format 


Record length is fixed. The file label contains fields 
indicating the number of records in the file (FDRINRECS) and_ the 
number of records in the last block of the file (FDR1EREC). 


The length of the record is a fixed value (UFBRECSIZE). This 
value is set when the file is created (OUTPUT mode). This value 
is held in UFBRECSIZE and used for data transfer between the 
user-record-area and the file when an existing file is processed 
under RAM. Valid record length is 1-2048. 


Indexed Disk File 
Fixed Length Records (Blocked) 


Disk Block (2K) 


| BL | Record 1 |! Record 2 | Record3 |! /// |. Data | 
| | | | | | Level | 
| | | | | Chain | 


Record Format 


| | Key | | 
| | field | | 


fixed length record 


Records are fixed length. Each record has a key field upon which 
the records are ordered. The record length can range from 1-2040 
bytes. The key length can range from 21-55 bytes. The key 
position can range from 1 up to any value such that the whole key 
fits within the length of the record. The key position field is 
numbered from 0 internally (UFBKEYPOS is numbered from 0). 


The file label contains a record count (FDRINRECS). 


An indexed file contains both data blocks and index blocks. The 
index blocks form a tree structure by which data blocks may be 
located. Only DMS routines manipulate index blocks. Under RAM, 
the user program has access only to data records. Index blocks 
have a chain field and a block prefix (BL) similar to data 
blocks. The block prefix field (BL) is described in the next 
section on variable length records. 


Consecutive Disk File 
Variable-Length Records (Blocked) 


Disk Block (2K) 


| BL {| Record1 {| Record 2 | Record 3 | ///// | 
| | | | | 


The two-byte block prefix (BL) indicates the length of the block 
(i.e., sum of record lengths plus 2). DMS blocks records as 
tightly as possible during file creation (OUTPUT mode). 


Record Format 


| RL | data portion of record | 


a rene Gent ret NRgeeneeeNent 


The two-byte record prefix indicates the length of the record 
(i.e., data portion of record plus 2). UFBRECSIZE at SVC OPEN 
(OUTPUT mode) is the maximum record size; this value is stored in 
the label. Valid record length is 1-2024. 


For OUTPUT mode, UFBRECSIZE indicates the length of the record in 
the user-record-area. The record prefix (RL) is not included in 
this length; the record prefix is not present in the 
user-record-area. UFBRECSIZE may be varied by the user program 
in order to write different sized records. The data management 
system supplies the BL and RL prefixes. 


For existing files, UFBLRECSAVE equals the maximum record size 
(from the file label). UFBRECSIZE is set by DMS to equal the 
length of the record in the user-record-area after each read. 
The RL is not moved to the user-record~area (i.e., UFBRECSIZE is 
set to RL2). There are two minor restrictions for variable 
length consecutive files (as opposed to fixed lengths) ; 


1. Read relative is an invalid function-request for 
variable length consecutive files. The START SKIP and 
START BEGIN function-requests are available for 
positioning within a variable length consecutive file. 


2. The record size (UFBRECSIZE) may not be changed when 
REWRITING a record (flagged as invalid function- 
request). 


Compression Option 


A compression option is available for variable length con- 
secutive files. This option can allow significant saving in disk 
space. The option is requested when the file is created. In this 
case, the data portion of the record is stored in compressed for- 
mat (as described by the COMPRESS and EXPAND machine instructions). 


Record Format 


| RL | compressed data | 


rr en RN 


The use of the compress option is transparent to the user program 
under RAM*; however, the REWRITE function is not allowed for 
consecutive files with compressed variable-length records. DMS 
performs compression on OUTPUT (WRITE) and expansion on INPUT 
(READ). The value of UFBRECSIZE, UFBLRECSAVE and the file label 
is always the length of the noncompressed record (i.e., for a 
READ, UFBRECSIZE is set to the noncompressed length regardless of 
the value of RL). For compressed format, the maximum record size 
(established at file creation) is 2024. 


NOTE: 


Print records are stored as compressed variable 
length records when directed to a disk file. 


“ If Read Nodata is used, the user receives a pointer to the 
compressed data portion of the record (in a buffer). In 
this case, the user program must expand the record directly. 


Indexed Files with Variable Length Records 


The indexed filed organization is available with variable length 
records. In this case, UFBRECSIZE is used to indicate the length 
of the record read for existing files. The full range of 
function-requests available with indexed files (fixed-length 
records) is also available for indexed files with variable-length 
records. The compress option is also available. The length of 
the record may be changed when rewriting a variable-length record 
to an indexed file. DMS will handle any index updating required. 


Function-Requests and Function-Request Modifiers — RAM 


There are five DMS function-requests (READ, WRITE, REWRITE, 
DELETE, and START). Macroinstructions have been provided for 
these function-requests. The macroinstructions also provide for 
all the possible function-request modifiers. The preceding charts 
illustrate which of these function-requests are available under 
RAM for a particular Open Mode/Disk File Organization combination. 


Read (NEXT, RELATIVE RECORD NUMBER or KEY) - The indicated record 
is read into a system buffer by DMS if not already present. The 
record is moved from the buffer to the user record area 
(addressed by UFBRECAREA). For fixed-length records, the record 
length is taken from UFBRECSIZE. 


Read Modifiers 


a. NEXT - The desired record is the next record in the 
file. After OPEN, READ NEXT yields record number 1. 


b. REL ~ The desired record is indicated by the relative 
record number in the fullword addressed by the 
UFBKEYAREA. REL is only available for consecutive 
files with fixed length records. 


c. KEYED ~ The desired record is indicated by the _ key 
starting at the location addressed by UFBKEYAREA. The 
length of the key is UFBKEYSIZE. KEYED is only 
available for indexed files. 


d. NODATA - The record is not moved to UFBRECAREA; 
instead, the address of the record in the buffer is 
returned in general register 1. 


e. HOLD - The HOLD modifier is used in I/O or Shared mode 
to indicate that the record just read may be rewritten 
or deleted. In this case, DMS will retain the current 
block for the record so that the rewrite or delete may 
occur. The HOLD modifier is required in all cases 
where the record is to be rewritten. 


Read File Status With UFBEODAD Return 


The following file status conditions cause a return to _ the 
program at the address in UFBEODAD. These conditions arise when 
the indicated record cannot be found. 


FS='10' -  End-of-data. A READ NEXT function request 
attempted to read past the end of the file. 


FS='23' - Record not found. A READ REL function supplied a 
relative record number equal to zero or greater 
than the highest record number in the file; ora 
READ KEYED function~request supplied a key value 
which was not equal to any key value in the file. 


Write 
For OUTPUT mode (file creation) or EXTEND mode, the record is 
moved from the user-record area to the file. The record be- 


comes the last record in the file. For indexed files, the key in 
the record written must be greater than the preceding key value. 


f= 


For indexed files in I/O or SHARED mode, the record is moved from 
the user-record area to the file. The key field of the record 
must not be the same as a key already in the file. There are no 
modifiers for the write-function request. 


Write file status with UFBEODAD return. 


The following file status conditions may occur when using the 
WRITE function-request to process an indexed file under RAM. 


FS='21' - Record key out of sequence - OUTPUT mode 
FS='22' - Duplicate key ~ I/0 or SHARED mode 


FS='24' - End of primary extent--OUITPUT mode. Insufficient 
Space was provided; the file may be CLOSED; 
additional records may be added in I/O mode. 


Rewrite 


The last record must have been read with the HOLD option. The 
record is moved from the user-record area to the file. For 
variable length records, the length must be unchanged. For 
indexed records, the key field of the record must be unchanged. 
There are no modifier values for rewrite. 


Delete 


The last record must have been read with the HOLD option. The 
record is removed from the file (indexed files only). The 
content of the user-record area is not used. 


Start 


The start function can be used for three different purposes under 
RAM: 


a. Switch Processing Mode--this option is available for 
consecutive files, fixed length records, open mode of 
OUTPUT or EXTEND. The modifiers are START OUTPUT (sets 
the number of records in the file to zero), START 
EXTEND (allows the file to be extended by subsequent 
WRITES) or START 1/0 (allows READ and REWRITE 
operations after setting temporary end-of~-file 
indicator); functions available are READ, REWRITE, and 
START OUTPUT and START EXTEND. 


If Start I/0 is used, an additional option is available. If 
UFBVAM is set in the modifier byte, then the Access Method will 
be switched. If switching from BAM to RAM, UFBNRECS may be 
provided to allow exact setting of the end-of-file indicator. 


Position to a Record within the File--this is the common 
usage of START under RAM. Positioning within an indexed 
file is accomplished using modifiers EQUAL, GREATER 
THAN, or GREATER THAN OR EQUAL. Positioning within a 
variable-length consecutive file uses START SKIP where 
the word addressed by UFBKEYAREA indicates a _ signed 
number of records to be skipped. START BEGIN is also 
available to position to the first record of a consec- 
utive variable-length file. The HOLD modifier is 
available for START on an indexed file. The generic 
keysize feature (UFBGKSIZE) is also available with the 
START request on an indexed file. 


HOLD a file, or release a file or record from HOLD 
status (shared mode - ignored in IO mode). 


START HOLD acquires protected update (HOLD) rights to the entire 
file. This HOLD status is released by START RELEASE, which 
removes any file or record from HOLD status for the issuer. 


Start Function UFBEODAD Returns 


These UFBEODAD returns may occur when START is used to position 
within a file. 


FS='10' 
FS='23' 
FS='24' 


~  end-of-file. End of file can occur when the value 
in UFBKEYAREA for START(SKIP) causes the end-of-file 
(positive value) or start-of-file (negative value) 
to be exceeded. 


- record not found when START EQUAL issued. 
- record not found when START (GREATER THAN) or START 


(GREATER THAN OR EQUAL) issued; key value is greater 
than any key in the file. 


Notes for Record Access Method (RAM) 


1. 


File size specification for file creation (OUTPUT MODE): 
The amount of disk space allocated for a file is deter- 
mined by DMS. DMS uses a record number count supplied by 
the user program (UFBNRECS). For indexed files, DMS also 
calculates the additional space required for the index. 
Extra space can be released when the file is closed. 


Buffers - The user program can specify the buffer size 
to be allocated under RAM. A large buffer size can 
represent a significant performance improvement for 


sequential access of the _ file. The buffer size is 
supplied in UFBBUFSIZE before SVC OPEN. The buffer size 


must be a multiple of 2K (otherwise the default size is 
used). The buffer size may also be adjusted by DMS 
depending on the maximum data transfer size supported by 
the device. Default buffer size is 2K. 
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3. Record size at SVC OPEN (NonOUIPUT mode) - For existing 
files, UFBRECSIZE is used to request a file with a 
specific record size. UFBLRECSAVE is filled in from 
the record size field in the file label. If 
UFBRECSIZE = 0 at SVC OPEN, the field is simply filled 
with the value from the file label. 


4. Anticipatory buffer priming is automatically performed 
under RAM. Also, sequential rewrites (or deletes) are 
blocked. 


7.2.2 Block Access Method (BAM) - Disk Files 


The unit of data transfer is the physical disk block; the length 
of a disk block is always 2K (2048 bytes). This Access Method 
can be selected by setting UFBF1BAM before SVC OPEN. Files are 
accessed in a file-organization-independent manner. This access 
method supports: 


a. random or sequential access of any disk file using 
relative block number in file (from 1). The unit of 
transfer is 2K bytes. 


b. creation of new disk files by copying existing disk 
files in a file-organization-independent manner. 


C. user program blocking or deblocking of records. 
The Open Modes supported under RAM are also supported under BAM. 
The only significant difference is the unit of data transfer 
(always 2K under BAM). 


FUNCTION REQUESTS PROVIDED FOR DISK FILES UNDER THE DMS BLOCK 
ACCESS METHOD 


FILE ORGANIZATION - ANY 
RECORD FORMAT - ANY 


| Input | Output | 1/0 | *Extend | Shared | 
| Read ae | x | | | 
| Write | | xX | | X | | 
| Rewrite | | | x | | | 
| Start | | xX | | X | 
| Delete | | | | | | 


*“ ~ Extend Mode is not supported for indexed files under BAM. 


Function-Requests and Function-Request Modifiers - BAM 


The preceding chart indicates the function-requests available 
under BAM for a particular open mode. The Block Access Method 
allows the user program to access any disk file in a file 
organization independent manner. 


Read - The indicated 2K disk block (NEXT or RELATIVE BLOCK 
NUMBER) is read into a system buffer by DMS if not already 
present. The block is moved from the buffer to the user-record 
area as addressed by UFBRECAREA; the length is 2048 bytes. 


Read Modifiers 


a. NEXT - The desired block is the next block in the 
file. After SVC OPEN, READ NEXT yields block number 1. 


b. REL - The desired block is indicated by the relative 
block number in the full-word addressed by UFBKEYAREA 
(from one). 


c. The NODATA and HOLD modifiers are available under BAM 
in the same way as described in RAM. (The KEYED 
modifier is not used under BAM.) 


Read File Status Using UFBEODAD Return 


The end of file (FS='10') and record not found (FS='23') 
conditions occur under BAM the same as they occur under RAM. 


Write - The 2K block is moved from the user-record area to _ the 
file. The block becomes the last block in the file. There are 
no modifiers; the UFBEODAD return is not taken for a write 
function-request under BAM. 


Rewrite - The last block must have been read with the HOLD 
option; i.e., the preceding function-request must have been a 
READ with the HOLD modifier. The block is moved from the user 
record area to the file. No modifiers are used with the rewrite 
command. 


Start - The start function is used to switch processing modes in 
BAM. This function is available in OUTPUT or EXTEND modes. The 
modifiers allowed a START OUTPUT, START EXTEND and START I/O. No 
UFBEODAD returns are taken when switching modes. 


7-13 


Notes for Block Access Method (BAM) 


l. 


File size specification for file creation (Output 
Mode): The amount of disk space to be allocated for a 
file may be specified using a record number count (from 
UFBNRECS) as in RAM. However, under BAM, the user 
program may optionally specify file size as a number of 
2K blocks (UFBNBLKS) by setting UFBF4BLKAL. In this 
case, UFBNBLKS contains the number of blocks to be 
allocated; UFBNRECS is not used for disk space allo- 
cation. If UFBNBLKS is used and sufficient disk space 
is not available, the program will be cancelled (unless 
an OPEN EXIT has been supplied). The program will also 
be cancelled if UFBF4BLKAL is set and UFBNBLKS is zero. 


Buffers - The user program can specify the buffer size to 
be allocated under BAM by supplying an appropriate value 
in UFBBUFSIZE before SVC OPEN. A larger buffer can 


improve performance for sequential access of the file. 


Record Size at SVC OPEN - For Output mode, the value of 
UFBRECSIZE will be placed in the file label. For other 
modes, UFBRECSIZE may be used to specify the particular 
record size desired. After SVC OPEN, UFBLRECSAVE 
contains the record size (from the file label); 
UFBRECSIZE is set to 2048 after OPEN. 


Anticipatory buffer priming is automatically performed 
under BAM. 


Setting Number of Records in File at Close - The Block 
Access Method operates in a file organization 
independent manner. Therefore, at SVC CLOSE, additional 
information may be required in order to update the file 
label correctly for OUTPUT or EXTEND mode. 


The number of the last block in the file is maintained by DMS in 


UFBEBLK. 


The additional information required at CLOSE is 


dependent on the file organization. 


a. 


Fixed Length Consecutive - The total record count 
(UFBNRECS) should be supplied (this includes the number 
of records in the last (perhaps partial) block). The 
default is a DMS supplied count based on a full last 
block. The user supplied value (UFBNRECS) is ignored if 
it is inconsistent with UFBEBLK. 


Variable Length Consecutive - The record count should be 
supplied (UFBNRECS). Otherwise, DMS will set a_ record 
count assuming that all records are maximum size. This 
approximate DMS default value is only used if no other 
value has been supplied (i.e., UFBNRECS=0). 


7-14 


c. Indexed Files - The following fields are required before 
SVC CLOSE: UFBEREC, UFBNRECS, UFBHXBLK, UFBPTRD, and 
UFBDABLK. These values should be taken from the Input 
file for the file copy application. (Other than the 
file copy application, it is not recommended that 
indexed files be created under BAM.) 


7.2.3 Physical Access Method (PAM) - Disk Files 


The unit of data transfer is defined by the user-program. No 
buffer support is provided by PAM. This Access Method can be 
selected by setting UFBF1PAM before SVC OPEN. Files are accessed 
in a file organization independent manner. This access method 
supports: 


a. random and asynchronous access of any disk file. 


b. use-initiated physical 1/0 operations of more than one 
physical disk block. 


c. user-implemented buffering strategies. 

The following Open Modes are supported under PAM: 

a. Output mode - This mode supports the (sequential) 
creation of a file. The user-program controls the units 
of data transfer; the block number in file is adjusted 
by DMS for the length transferred. The data is written 
to the end of the file. 


b. Input mode - This mode supports retrieval of data _ from 


the file. Data retrieval is random; the user-program 
supplies both the data length and the block number in 
file. The user-program may pass through the _ file 


sequentially by updating the block number appropriately. 


c. 1/0 mode ~ This mode supports retrieval and modification 
of records in the file. The REWRITE function is random; 
the user-program supplies the data length and block 
number in file. In PAM, the REWRITE function need not 
be preceded by a read function. 


FUNCTION-REQUESTS PROVIDED FOR DISK FILES UNDER THE DMS PHYSICAL 
ACCESS METHOD 


FILE ORGANIZATION - ANY 
RECORD FORMAT - ANY 


| | | 
| Read ee eee | x | | 
| Write | | xX | | | 
| Rewrite | | [ xX | | 
| Start | x | xX | x | | 
| Delete | | | | 


Function-Requests and Function-Request Modifiers - PAM 


The function-requests used in the Physical Access Method have two 
common characteristics: 


a. The data length desired is set in UFBBLKSIZE. 
UFBBLKSIZE is 2 bytes long; it is considered as a 
positive number. The data length specified must be a 
multiple of 2K. After the data transfer is initiated, 
UFBBLKSIZE is set to the data length actually 
transferred. The data length actually transferred may 
be less than the requested data length due _ to 
end-of-file truncation, end-of-extent truncation or 
end-of-cylinder truncation. 


b. The user-program must issue a START(WAIT) function- 
request in order to wait for I/O completion. DMS does 
not wait for 1/0 completion in PAM. 


Read - The data as indicated by the block number in the fullword 
addressed by UFBKEYAREA (block number from 0) and the contents of 
UFBBLKSIZE (data length) is read into the user-record-area 
addressed by UFBRECAREA. UFBBLKSIZE is adjusted, if necessary, to 
reflect the length of the actual data transferred. There are no 
modifiers. UFBEODAD return with FS='23' is taken if the starting 
block number is beyond the end of the file. 


Write - The indicated data is written to the end of the file. 
UFBBLKSIZE is updated to indicate the length of the data 
transfer. DMS also updates the next block number for the data 
blocks transferred. After OPEN, the block number is 0. There are 
no modifiers. 


Rewrite - The data as indicated by UFBRECAREA and UFBBLKSIZE is 
written to the file starting with the block number from the _ word 
addressed by UFBKEYAREA. UFBBLKSIZE is then adjusted to reflect 
the length of the data actually transferred. There are no 
modifiers. UFBEODAD return with FS='23' may be taken for Record 
Not Found (as in Read). 


Start - The start function is primarily used with the WAIT 
modifier to wait for I/0 completion for the preceding READ, WRITE 
or REWRITE command. In OUTPUT mode, the modifiers OUTPUT, EXTEND 
and I/0 are available for mode switching (as in the other access 
methods) . 


Notes for Physical Access Method (PAM) 


1. File size specification for file creation (Output 
mode). The amount of disk space to be allocated may be 
specified as in BAM (record count or block count). 
Record size at SVC OPEN is also handled as in BAM. 


2. PAM uses no buffers, all 1/0 is performed using the 
user-record-area directly. 


3. Setting the number of records in the file at SVC Close 
requires the same file-organization-dependent 
information as in BAM. 


7.2.4 Notes on 2200VS Disk Files 


1. File labels - The VTOC holds the file labels (File 
Descriptor Record - FDR) for all the files on a disk 
volume. The FDR fields defined below are of particular 
interest for DMS routines. 


a. FDRIRECSIZE - size of logical record. This field 
indicates logical record size for fixed-length 
records. For variable-length records, this field 


is the maximum record size for the file. This 
field is only set at file creation. 


b. FDRIBLKSIZE - blocksize; always 2048. 


c. FDRINRECS - record count. This field indicates the 
number of logical records in the file. This field 
is not used by DMS as the end-of-file indicator. 


d. FDRIEBLK - last block in file. This field contains 
the block number (in file from 0) of the last used 
block in the file. This field is set for the last 
block number in file regardless of the file 
organization. This field (in conjunction with 
FDRIEREC if necessary) is used by DMS as the end of 
file indicator. 


FDRIEBLK is a sufficient end-of-file indicator for 
variable-length records since in this case the end-of-block 
condition is determined by the contents of the block. Indexed 
files use the data chain for end-of-file detection; FDRIEBLK 
(plus 1) serves as a free space pointer in this case. 
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For fixed-length records, FDRIEREC is used as a count of the 
records in the last file block; i.e., for fixed-length records, 
the end-of-file indicator is FDRIEBLK with FDRIEREC. 


FDRIEREC is 1 for variable-length records. For indexed files 
FDRIEREC is used as an index level count (used by DMS only). 


FDRINRECS, FDRIEREC an FDRIEBLK are always updated as a group by 
CLOSE. They are updated under RAM for OUTPUT and EXTEND modes 
and for indexed file SHARED and I/O modes. 


FDRLRECSIZE is never changed by SVC CLOSE. DMS does not support 
the use of different logical record sizes under RAM. FDR1IRECSIZE 
always indicates the noncompressed maximum record size for files 
containing compressed variable-length records. 


2. UFB fields - The following fields are availble to the 
user-program for inspection during DMS processing. The 
uses of other UFB fields should not be assumed. For 
disk files, no fields other than the modifier bytes, 
UFBRECAREA, UFBKEYAREA, and the error addresses’ should 
never be changed by the user program while the file is 
open (except for setting required values in certain 
fields immediately before closing the file when using 
BAM or PAM). Also, UFBRECSIZE and UFBGKSIZE (indexed 
files) are modifiable in certain circumstances. 


a. UFBLF, UFBLFMOD - these fields contain the last 
function and last modifier value. 


b. UFBLRECSAVE - this field contains FDRIRECSITE after 
a file is OPENED. 


c. UFBRECSIZE - this field contains the record size 
for fixed-length records under RAM. This field 
contains the current record length under RAM for 
variable-length records. This field contains 2048 
under BAM. 


Note that UFBNRECS is not always maintained during DMS 
processing. Also, UFBNRECS is always set to 0 by SVC OPEN for 
OUTPUT mode. UFBNRECS is available after OPENING an existing 
file (equals FDRINRECS). UFBRES3 contains the UFBNRECS value 
(used for space allocation) after SVC OPEN - OUTPUT MODE. 
(UFBRES3 may be re-used during DMS processing.) 


Access Method notes - VS disk files can be accessed or 
created by any access method. (However, creation of an 
indexed file under BAM or PAM is generally restricted to 
the file copy case, since no index building support is 
supplied.) Selection of an Access Method will gener- 
ally depend on the unit of data transfer desired or the 
file-organization support desired (e.g., indexed files 
under RAM). RAM provides the fullest DMS support. BAM 
can be used to advantage for consecutive files to reduce 
DMS overhead by performing user-program blocking and de- 
blocking. Significant sequential performance improve- 
ments may be accomplished in RAM or BAM by requesting a 
larger buffer at OPEN. PAM offers the most flexibility 
and the least DMS support; it is recom- mended primarily 
when data movement is to be minimized or when a_ flexible 
user-supported buffering scheme is desired. 


NOVTOC diskettes ~ This section has dealt with disk files 
which reside on a volume with a VIOC (i.e., disk files 
which have an associated disk file label). The diskette 
without a VIOC is used primarily as a medium for exchang- 
ing information between the VS system and other computer 
systems. The DMS support for NOVTOC diskettes includes 
all three access methods. In addition, the user-program 
can select any logical record size from 1-7-2048 since 
there is no file label information available. The 
following restrictions do notapply to NOVTOC volumes. 


1. indexed files are not supported 
2. extend mode and shared mode are not supported. 


In order to have the full range of VS system support and utility 
support, it is recommended that NOVTOC volumes be copied to 


standard 
in place. 


pe 


disk files before processing rather than being processed 


Specification of File Organization and Record Size at 
SVC OPEN. 


The fields UFBFORG and UFBRECSIZE may be supplied by the 
user program in order to request a specific file organ- 
ization or record size. If these fields are zero, then 
any file organization or record size is allowed. These 
fields are both required (non-zero) for OUTPUT mode in 
which case the values are stored in the file label. 


The following file organizations are supported. (The 
only valid organizatons allowed in the file label.) 


a. Consecutive file; fixed-length records UFBFORGCONSEC. 
b. Program file; fixed-length records as described in 


VS Object format (1024 nominal record’ size) 
UFBFORGCONSEC + UFBFORGPROGRAM. 
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c. Consecutive file; variable length records 
UFBFORGCONSEC + UFBFORGVLEN. 


d. Indexed files; fixed records UFBFORGINDEXED. 


e. Indexed files; variable length records 
UFBFORGINDEXED + UFBFORGVLEN. 


f. Print file; variable length records (compressed) 
UFBFORGCONSEC + UFBFORGVLEN + UFBFORGPRINT. 


Notes on File Organization 


a. 


The 


For OUTPUT MODE, if UFBFLAGSCOMP is set (i.e., 
compression option), then SVC OPEN’ will force 
UFBFORGVLEN=1 so that a file with compressed variable 
length records will be created. 


For nonOUTPUT mode, any consecutive file will be 
accepted if UFBFORG = UFBFORGCONSEC at SVC OPEN. 


For any mode, if UFBFORG = UFBFORGCONSEC + UFBFORGPRINT, 
SVC OPEN will set UFBFORGVLEN and UFBFLAGSCOMP in order 
to generate a standard print file. (CUFBFORGPRINT 
indicates that the user program has supplied a _ two-byte 
print control field for each record.) 


Note 
FDRIORGCONSEC + FDRIORGPRINT is not a valid value 
for the file label (FDR1ORG). 


following list indicates the valid range of values for 


UFBRECSIZE when a file is being created in OUTPUT mode. (These 
same values also apply when UFBRECSIZE is specified at SVC OPEN 
for nonOUTPUT mode.) 


a. 


b. 


Cc. 


Consecutive file; fixed-length records 1-2048. 
Indexed file; fixed-length records 1-2040. 


Variable length records with or without the compress 
option - 1-2024 (represents noncompressed size). 


The compress option may be set using UFBFLAGSCOMP when 
creating a file in OUTPUT mode. This flag is ignored for fixed 
length records. This flag is not considered to be part of the 
file organization. 


7.3  2200VS INDEXED FILE SUPPORT 


This section describes 2200VS Indexed Files and the access level 
support provided by the 2200VS Data Management System (DMS). 
Indexed files provide efficient sequential access and random 
access by primary key. The record formats available are fixed 
length, variable length, and compressed. The topics covered in 
this section are: 


Indexed File Creation 

Accessing an Existing Indexed File 

Buffer Options for Indexed Files 

Indexed File Structure 

Functional Overview of Alternate Indexed File Support 
Alternate File Error Log 

Overview of Indexed and Alternate Indexed File Structures 
Internal DMS Record Formats for Alternate Indexed Files 
Shared Mode 

Log Files 

Advanced Sharing (Multiple Resources) 

Detailed Functional Overview for Shared Mode 

Summary of START Functions 


This section describes file access using the Record Access Method 
(RAM). It is intended as a detailed guide to 2200VS DMS _ support 
of Indexed Files. This section also includes descriptions of 
actual 2200VS file structures. While an in-depth understanding 
of the file structure is not required to effectively access 
indexed files, the sophisticated programmer should be able to use 
the file structure information for performance and packing 
considerations and for lowlevel debugging. 


Indexed File Creation 


An Indexed file is created using OUTPUT mode. The number of 
records to be supplied in OUTPUT mode is used for initial file 
allocation. There is no restriction on the number of records 
which may be added later; also, no additional space for file 
expansion need be included at file creation. The format of a 
record in an indexed file is: 


| | Primary Key Field | | Data 
| | | Record 
| Position|Size| 


Primary key size and position is determined by the user. This 
information is stored in the file label. All records in the file 
must have a unique primary key value (duplicates not allowed). 
(For variable-length records, the minimum record size = position 
plus key size.) Primary key size can be from 1-255 bytes. 
Primary key position can be from 1 up to the maximum value (MAX = 
Record size minus key length). If data records are compressed, 
it is somewhat advantageous to have the Primary Key position be 
near the beginning of the record. 
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Records are added to the file in OUTPUT mode using the WRITE 
function. Each record must have a higher primary key value _ than 
the preceding record. The records are blocked and written to the 
file in OUTPUT mode. (The low-level index is also built as 
records are added; the full index structure is created only when 
the file is CLOSED (OUTPUT mode). This last feature (index 
creation at CLOSE) is used only in OUTPUT mode, i.e., in IO or 
SHARED mode the index structure is maintained for each 
function-request and no additional index update at all is 
required at CLOSE for these modes. 


OUTPUT mode provides very fast sequential loading (creation) of 
an Indexed file. However, it is possible to create an indexed 
file containing no records (record count = 0); in this case, 
records could be later added randomly in IO or SHARED MODE. The 
WRITE function-request in OUTPUT mode is significantly faster 
than the dynamic WRITE request available in I0 or SHARED modes. 


A file packing option is available in OUTPUT mode. This option 
allows data blocks and index blocks to be filled to 100% 
capacity. The default is 100% packing. Loose packing may allow 
subsequent random record additions to be processed without 
requiring a block to be split. Loose packing also has a slight 
effect on efficient allocation of Data Base Key values (to be 
described later). It should be noted that loose packing is never 
required and that loose packing has no significant effect on the 
number of records which may be added to the file at a later time. 


Accessing an Existing Indexed File 


An existing Indexed file can be accessed in INPUT, I0 or SHARED 
MODE. The functions available in INPUT MODE are: 


READ NEXT (next in primary key sequence from current 
position) 


READ KEY (primary key value supplied) 
START (KEY) (modifiers and generic keysize options; START 


KEY used to establish file position for READ 
NEXT) 


These functions allow records to be read; record modification is 
not. allowed. 


The additional functions available in IO MODE are: 


REWRITE must follow READ w/HOLD 


DELETE allows current record to be rewritten or deleted 


WRITE add record to file; record has unique primary 
key value. 


The functions available in SHARED mode are the same as those 
available in IO mode. 


The HOLD option for the READ function - READ NEXT and READ KEY 
may be used with the HOLD modifier (i.e., READNEXTHOLD and 
READKEYHOLD). The HOLD modifier bit has no effect in INPUT 
MODE. In IO mode the HOLD bit has two effects: 


1. A REWRITE or a DELETE may be issued for this record. 


2. The buffer containing the record will not be used for 
sequential buffer priming. 


Buffer Options for Indexed Files 


When an indexed file is OPENED buffers are assigned; these 
buffers are used by DMS when performing the user's function- 
requests. The three buffer options available are discussed here. 


1. Fixed Buffer Strategy - This strategy is used if 
neither of the two options below are indicated (i.e., 
this is the default strategy). Two buffers are 


allocated. For Read functions, one buffer can hold the 
Index ROOT block while the other is used for subsequent 
index levels and the data block itself. The two 
buffers are used effectively when the Block Split 
operation is required for file growth. 


2. Buffer Pool - This strategy may be selected by the 
user. The user creates a Buffer Control Table (BCTBL 
using BCTGEN) which is filled in by OPEN and maintained 
by DMS. All indexed files per task may be accessed 
from the same buffer pool. Also, more than one buffer 
pool can be used within the same program. 


A buffer pool consists of a group of 3 to 60 buffers; 
each buffer is 2048 bytes (2K) and is acquired from the 
Segment 2/task using GETBUF. The BCTBL requires 56 
bytes/buffer for buffer management. 


There is no restriction of the order of opening and 
closing files using a buffer pool. 


The Buffer Pool is managed using an LRU approach; all 
write operations are initiated directly (rather than 
being initiated at buffer replacement time, e.g., 
pageout by page). The internal features of DMS buffer 
pool maintainence are adjusted for performance in an 
interactive environment. 


3. Large Buffer Strategy - This strategy may be selected 
by the user. In general, two buffers are assigned; 
however, one of these is a large buffer (large buffer 
size can be from 4K to 18K). This strategy is 
available for INPUT mode. For INPUT mode _ and 
sequential access, this strategy can save many I0 
operations. 


These three strategies may be combined within a program if 
required. The use of buffer pooling for general indexed file 
random operations will certainly be helpful in significantly 
reducing the total number of I/0 operations. The sharing task 
also makes use of the buffer pool to provide access to a number 
of SHARED files with efficient performance. 


Indexed File Structure 


Indexed files contain a number of 2K blocks. However, the 
relationship between blocks is established using chain fields and 
pointer fields. (In an indexed file, block (m) and block (n+1) 
are not necessarily accessed in order.) 


Logical View of Blocks in a sample Indexed File 


ROOT 
I 


The above figure shows 3 levels. The first level is the ROOT 
block. The ROOT block is used when a primary key is supplied and 
a record is to be read. In the above figure, the ROOT contains 
POINTERS to 3 low-level index blocks. In turn, each of these 
index blocks contains POINTERS to the lowest level block - the 
structure. These lowest level blocks contain the data records in 
the indexed file. 
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The above figure shows 2 index levels and the lowest level of the 
structure (the record level). All blocks on one level are 
chained forward using a 3-byte CHAIN field at the end of each 
block. 


Type I blocks (above) contain index items. An index item 
consists of a key field and a 3-byte pointer to a block on the 
next lower level. The key field in the item is equivalent to the 
highest key in the block pointed to. 


Functional Overview Of Alternate Indexed File Support 


Introduction 


The alternate indexing facility for Wang 2200VS Indexed 
Files allows the creation of up to sixteen (extendable to 32 or 
64) alternate access paths to records ina file. A program may 
specify on WRITE and REWRITE functions the access paths through 
Which a particular record is to be accessible, and on READ and 
START functions may specify the access path to be used. 


Each alternate access path is implemented as a 
tree-structured index defined on a field (starting position and 
length) within the data record, and referenced within the file's 
label (and by programs) as an ordinal between 1 and 16. The Data 
Management System maintains a map with each record of the file, 
indicating the access paths through which that record may 
currently be accessed. 


New Fields for DMS Functions (UFB and AXD1) 


In discussing the Data Management functions, fields have 
been added to the User File Block; also a new block (AXD1) is 
used. The AXD1 is described in detail later; for the purpose of 
this section, it can simply be regarded as a UFB extention-type 
block. 


(1) AXDIMASK - A two-byte field into which a bit map is 
placed as a result of READ functions, indicating the currently 
available access paths for the record read. This field is to be 
set by the program before REWRITE or WRITE requests to indicate 
the access paths to be made available for accessing the record 
Written. (A variable mask size from 1-8 bytes is a planned 
additional feature.) 


(2) AXDIALTINX - A one-byte field containing a binary 
number from 0 to 16. This indicates the access path (index 
structure) to be used on READ and START functions. Zero (0) 
indicates the primary index structure. One (1) through sixteen 
(16) select alternate index structures. The field contains 0 
when the file is opened. 
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(3) UFBALTCNT - One byte, containing in binary the number 
of alternate index structures which can be processed using this 
User File Block. A file with more alternate access paths than is 
specified in this field will require that the Data Management 
System allocate additional storage (in the requestor’s segment 2 
buffer area) at OPEN time in which to keep alternate index 
Structure descriptions. Compilers are expected to supply a 
proper value in this field and in UFBALTPTR, and to reserve 
sufficient space at the location addressed by UFBALTPTR to hold 
the index structure descriptions; they should not rely on the 
Data Management System to allocate buffer space, since that is a 
relatively inefficient use of memory. (Also see notes on 
AXDI1~AREA at end of chapter.) 


(4) UFBALTPTR - Three-byte address of an area (User File 
Block appendage or other segment 2 area) to contain alternate 
index structure descriptions (from AXDIENTRY). If zero, space in 
the segment 2 buffer area will be allocated. 


DMS Functions 
READ Function 


A READ by key value uses AXDIALTINX to determine the proper 
access path. If the requested record can be found, it is placed 
in the record area. AXDIMASK is set to indicate the available 
access paths to that record. If duplicate key values are allowed 
on the specified access path, all other records with the same key 
value can be retrieved by repeatedly issuing READ NEXT requests. 
AXDIALTINX is_ unchanged. If the access path specified by 
AXDIALTINX does not exist, an invalid key condition occurs (as if 
the access path existed, but no records were accessible through 
it). 


A READ NEXT uses AXDIALTINX to determine the current access 
path. It reads the next record in sequence by the key field 
associated with that access path. (Immediately after OPEN, this 
is the first record on the primary access path.) AXDI1MASK is set 
as for READ by key. The established key of reference access path 
corresponds to the AXDIALTINX path (where AXDIALTINX was set by a 
previous function request). If AXDIALTINX is changed by the 
program between an OPEN, READ, or START, and aé_ following 
READ-NEXT, that READ-NEXT will fail and ‘Invalid Function 
Sequence' will be reported in the UFB file-status bytes; in this 
case, the UFB error exit is taken if present. 


Invalid-Key and End-Of-File conditions occur under the same 
circumstances as for primary key access. (Notice, for example, 
that if 10 records are accessible through the first alternate 
access path of a file, End-Of-File status will be set after not 
more than 10 successive READ NEXT requests on that access path, 
no matter how many records are in the file.) 
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WRITE Function 


A WRITE request does not use AXDIALTINX, but sets it to 
zero (indicating the primary access path) when the WRITE 
completes. The new record becomes accessible through alternate 
access paths corresponding to the bits on (1) in AXDIMASK. If 
bits not corresponding to any defined access path are set, the 
WRITE operation fails with file status indicating ‘Error, Invalid 
Mask' and the error exit is taken. Unless duplicate key values 
are allowed for an access path, an attempt to WRITE or REWRITE 
(I0 mode) a record containing such a value results in the same 
file status as for a WRITE with duplicate primary key (22), and 
the entire operation fails. (The file is not changed.) 


Duplicate key errors for output mode are not detected until 
CLOSE, at which time only the first of the records involved in 
the duplication is recorded in the alternate index structure for 
this access path and the CLOSE proceeds; the file status in the 
UFB is set to ‘Invalid Key, Duplicate (22)' and is available 
there for examination by the program after CLOSE (an error-log 
file can be optionally created; this feature is described later). 


REWRITE Function 


REWRITE does not use AXDIALTINX. It affects the current 
record, after READ WITH HOLD. The replaced record becomes 
accessible through the alternate access paths corresponding to 
the bits on (1) in AXDIMASK (as for WRITE). The record is no 
longer accessible through the access paths corresponding to zero 
(0) bits in AXDIMASK. (In this sense, REWRITE is equivalent to 
DELETE followed by WRITE.) The REWRITE operation fails with 
‘Invalid Mask' if any invalid mask bits are set (as in WRITE), or 
with ‘Invalid Key, Duplicate (22)' if an alternate key field for 
which duplicates are not allowed contains a duplicate key. 


DELETE Function 


DELETE affects the current record, after READ WITH HOLD. 
AXDIALTINX and AXDIMASK are not used. The deleted record is no 
longer available on any access path. 


START Function 


AXDIALTINX determines the key to be compared for equal 
(eq) , greater-than (gt), or greater-than-or-equal (ge) 
conditions. When duplicate keys are allowed on the specified 
access path, START positions the conceptual current~record-pointer 
to the first of these, so that successive READ NEXT requests will 
retrieve them all in primary key order. 


OPEN Function ~ Existing File 


AXDIALTINX is zero after OPEN, thus indicating that the 
primary key is the current key of reference, and AXDI1MASK 
indicates the existing index structures (as indicated in the file 
label). A READ NEXT retrieves the first record in primary key 
sequence, 


OUTPUT Mode File Attribute Specification 


UFBALTCNT and UFBALTPTR must be supplied in OUTPUT mode. 
UFBALTPTR must address an AXD1 control block with AXDIMSIZE 
supplied (2 in binary for the first implementation), and 
containing alternate index structure description entries (as 
defined in control block AXD1) for each alternate access path to 
be defined. 


The key field ordinal (AXD1XORD), key location 
(AXDIKEYPOS), key length (AXDIKEYSIZE), and selectable options 
(AXDIEFLAGS) must be supplied in each entry. Selectable options 
in AXDIEFLAGS are: duplicate keys allowed and key compression in 
index structure. 


Alternate File Errorlog (OUTPUT Mode) 


When an alternate indexed file is created in OUTPUT mode, 
the user program presents records in ascending primary key 
sequence to DMS. (Each record has an associated user-supplied 
access mask.) The primary index structure is created as records 
are added. The alternate key information is held in a _ group of 
work records until the file is closed. 


At SVC CLOSE, a program (BUILDALT) is called to create the 
alternate tree structures using these work records. The work 
records are sorted and the alternate tree structures are built. 


Only during this last phase is it possible to detect the 
following error condition: 


An alternate access path which does not support duplicates 
has duplicates (i.e., two or more records have the same alternate 
key value for the particular access path). 


In this case, the record with the lowest primary key value 
will be accessible through the access path while other duplicates 
are not. (However, no masks in the records are updated.) 


If this error occurs, the program (BUILDALT) will issue a 
message giving the user the choice of creating an error log file 
or not. 


If an error-log file is to be created, BUILDALT will use 
filename = ‘ERRORLOG' in the library (and volume) containing the 
alternate file. This consecutive file will contain fixed length 
records in the following format: 


BYTES 1-2 = 2 unpacked decimal digits representing the 
ordinal number of the access path (e.g., 
X'3031'). 

BYTE 3 = ASCII blank (X'20'). 

BYTES 4-N = primary key value of record in error (i.e., 


record not accessible through the access 
path). 


Using The Error Log To Correct Errors 


1. Records in error can be rewritten with appropriate mask 
and/or alternate key values. This would require a separate user 
program (in COBOL). 


2. If the access path definition was in error (i.e., 
duplicates should have been allowed), then the file should be 
re-created using a correct definition. 


Notes: 
1. Getting an error-log is always recommended. 


2. The alternate file can be read sequentially with 
the access masks intact in order to recreate the 
file. All functions on the file will perform 
correctly although records in error will not be 
accessible through access paths where an invalid 
duplicate condition occurred. 


3. Fixing all errors before further use of the file is 
recommended. 


Overview Of Indexed And Alternate Indexed File Structures 
Indexed Files 


- Consist of a primary-tree structure with data blocks at 
the lowest level. 


- Each data block contains records in ascending key 
sequence; the data records may be in one of the 3 
DMS~record formats. 


. Each data record contains a unique fixed-length 
imbedded primary key. 


‘ Blocks on levels other than the lowest level are index 
blocks; these index blocks have item size = PK size t 3 
(a 3 byte pointer to a block on the next lower level). 
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; All blocks in the primary tree (or any alternate tree) 
structure have a 2-byte block length (BL) prefix 
(DISP=0) and a 3-byte chain field (DISP=2045). 


Alternate Indexed Files 
: Contain a primary-tree structure. 
: Contain one or more alternate tree structures. 


‘ Contain a label block for alternate tree description 
and processing. 


The primary-tree structure is the same as for indexed files 
except that each data record has a 2-byte access mask. 


Internal Representation Of Low-Level Of Primary-Tree (ata 
Records Within Data Blocks) 


The record size in the file label (FDRIRECSIZE) does not include 
the mask length. Internally, however, the mask is always stored 
with the record and is reflected in the RL prefix for variable- 
length records or an adjusted internal record size (=RECSIZE plus 
MASKSIZE) for fixed length record processing. 


The access mask indicates through which alternate paths the 
record may be accessed. The access mask is not referenced as 
part of the record; it is present in AXDIMASK (through UFBALTPTR) 
and is never present in the user-record area. For variable- 
length data records, the record size supplied in UFBRECSIZE by 
the user (for REWRITE or WRITE) does not include the mask length; 
likewise, the value returned in UFBRECSIZE by DMS after a READ 
request does not include the mask length. 


There is one tree structure for each alternate index (access 
path). The lowest level of an alternate tree structure contains 
items of the form: 


i | | 
| Alternate Key | Primary Key | 
| Value (AK) | Value (PK) | 
| | | 


This item indicates that the data record with Primary Key = PK 
has the particular alternate field with value = AK. This 
fixed-length item will be used for the initial implementation 
(see note 2 below). 


Blocks on levels other than the lowest level are index blocks 


within the alternate-tree structure. These index blocks have 
item size = AK size +3. 
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An alternate indexed file also has an alternate index descriptor 
block (AXD1) as the first block in the file (block number 0). 


Initial Implementation Notes: 


1. For access mask = 2 bytes, 16 (max) alternate trees are 
allowed. All DMS related control blocks contain space 
for possible expansion to access mask size of 4 or 8 
bytes (with 32 or 64 maximum alternate trees). 


The access mask size is defined as 2 bytes for initial 
implementation. 


2. The low-level items are fixed length for a _ given 
alternate tree (size = PK size plus AK size); this fact 
is indicated in the information describing that tree. 
Variable-length, low-level items are a later extention 
(VLEN items will be useful for duplicates). 


Internal DMS Record Formats For Alternate Indexed Files 


The internal DMS record formats for data records and for 
work records are briefly listed here. Naturally, the formats for 
data records apply to all data records in the file regardless of 
open mode. 


The three DMS record formats are listed here for alternate 
indexed files. Note that the access mask is stored at the end of 
the record and that the mask is always maintained with its 
associated data (i.e., the mask length is included in the RL 
prefix for variable length records). 


Fixed Length 


Format | | 
| Data | Mask | 
| | 

Variable Length 

Format | | | | 
| RL | Data | Mask | 
| | | | 

Compressed 

Format | | | 
| RL | Data | Mask | 
| | (Compressed) | | 
| | | | 


Note that for compressed format, the length of the compressed 
data is RL minus 2 minus mask-size; the compressed data begins at 
RL+2 as usual. Note that the mask is not compressed. 


tas 0 


Work records are created from data records during OUTPUT mode DMS 
WRITE functions. These work records are sorted during CLOSE 
processing and used to create the low-level part of each 
alternate tree structure. 


Work Record 
Format 


| | | 

| XORD | Alt-key value | Primary Key 
| | | Value 

| | 


The length of each work record = 1 plus max (alt~key size) plus 
primary key size. (Stored in AXDI1ORECSIZE.) 


XORD refers to the ordinal tree structure number (AXD1ORD). For 
a work record containing an alternate key smaller than the 
maximum size, the work record contents beyond the end of the 
primary key field are undefined. Using fixed-length work records 
allows all records to be sorted on the same record size. 


SVC OPEN - Existing Alternate Indexed File 


The user supplies an AXD1-Area addressed by UFBALTPTR; the 
length is indicated by UFBALTCNT (length = (AXD1ENTRY-AXD1BEGIN) 
plus (UFBALTCNT * L'AXDIENTRY)). If either field is zero (or if 
the area is invalid as flagged by MCBRWIST), then no 
user-supplied AXDli-Area is used by SVC OPEN. This case is not an 
error; SVC OPEN allocates the appropriate AXD1-Area from the user 
buffer space. (No AXDl-Area is used for BAM or PAM.) 


The SVC OPEN requires almost no changes from normal indexed 
file support until the end of the routine when the UFB is set 
up. At this point, the appropriate DMS function vector addresses 
are placed in the UFB; also a third buffer is allocated 
(AXDIBCB). Block 0 in the file is the AXD1-Block; this block is 
read to a buffer area by SVC OPEN and then it is moved to. the 
AXD1-Area. The information in each AXDIENTRY ('label' 
information) is verified as in output mode (key size, key 
position and ordinal tree value). AXDIMASK is also verified as 
follows: 


a. Create existing tree mask while checking ordinal number 
values (for duplicate or invalid ordinal tree 
structure-AXD1XORD) . 


b. This existing tree mask must equal AXD1PMASK. 


If AXDIPMASK is invalid, or if any field within an AXDIENTRY is 
invalid, a cancel message indicating invalid label information is 
displayed. The AXDl~Area which is loaded is either user-supplied 
or allocated directly by SVC OPEN. 


After SVC OPEN, the following fields are set: 


a. AXDIALTINX = 03; AXDICURINX = 0 

*b. AXDIMASK = AXDIPMASK (indicating all trees) 
(AXDIPMASK is validated as part of label 
information verification) 

*c, UFBALTCNT = FDRIALTCNT (this is true after BAM 
and PAM OPEN also.) 

d. UFBALTPTR = address of AXD1-Area 

e. AXDIUFB = address of UFB 

f. AXD1BCB = buffer address and OFB pointer set 


For SHARED MODE, any user-supplied AXD1-Area is ignored. 


“After an alternate indexed file is opened in SHARED MODE, 
UFBALTCNT is zero and AXDIMASK is zero in the user's AXD1l-Area 
(from UFBALTPTR) . 


7.4 SHARED MODE 


SHARED MODE is an OPEN MODE which allows multiple user programs 
(in effect) to access the same file through IO MODE type 
functions (i.e., multiple realtime requests for record addition, 
deletion or modification are supported.) The function-requests 
available to the user-program in SHARED MODE are identical to 
those in IO MODE (some situations do occur in SHARED MODE, based 
on the need for exclusion between concurrent requests for the 
same record, which do not occur in I0 MODE). The user may have 
multiple files open in SHARED MODE. 


SHARED MODE is implemented on the 2200VS System through a SHARING 
TASK. This task has exclusive control of the file; it processes 
requests from user-programs one at a time and resolves any record 
conflicts. This task uses IO mode functions (with buffer 
pooling) for all file access. A mapping facility is provided by 
the 2200VS operating system (see SVC DTI) to allow efficient 
record transfer between a user task and the SHARING TASK. 


The SHARING TASK is a separate task (which does not require a 
workstation). It has its own Segment 1 and Segment 2 and _ runs 
unpriviledged. It (currently) has no special privileges (Ci.e., 
it must adhere to all the restrictions of unprivileged 
operation). The only distinguishing feature it has is a port for 
intertask messages whose name is "@SHR''. SVC OPEN and SVC CLOSE 
identify the SHARING TASK solely by PORT=@SHR. 


The two following figures show the general steps in a request for 
one user accessing a record in one SHARED file. 
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intertask 


boundary 

| 

i | 

| 
I | 1 | | | | | | 
| USER |_ request _ | DMS | | | SHARING |_1I/O MODE [FILE} 
| PROGRAM | i Interface | { IFMSGI TASK | request | 1 
| { | i 14 i | i] 

14 


The user-program's request is packaged as a function message 
(FMSG) by the 'called' DMS interface vector. (Interface vector 
addresses are placed in the user's UFB by SVC OPEN.) The FMSG is 
sent to the SHARING TASK. The SHARING TASK issues corresponding 
10 MODE request(s) using DMS on the file. 


intertask 
boundary 
| 
1 | 
| i I { i] | } ! | 
| USER | File Status! DMS 1 | IRMSGI SHARING | (record) | FILE | 
| 


{ PROGRAM | | Interface | { {TASK | | | 


The SHARING TASK receives file status as a result of the IO MODE 
operation. The SHARING TASK sends a response message (RMSG) to 
the interface vector. The interface vector moves the file status 
to the UFB. All OPEN, DMS, and CLOSE messages use the same 
message format: function message (FMSG) and response message 
(RMSG) . 


The steps for MAPPING THE RECORD AREA involve virtual memory 
Mapping such that the record area in the SHARING TASK Segment 2 
(which, for example, receives a record on a READ request) can be 
mapped to (and from) the USER'S SEGMENT 2 without any actual data 
movement. 


In a general environment, we have the following: 


IFiles opened byl 
}the SHARING | 
ITASK in I0 MODE] 


Many {Cail _ DMS |DMS | _intertask messages ISHARING| OMS | (exclusive | 
fuser | for SHAREDIINTERFACE!| (FMSG+RMSG) 1 TASK | i possession) 
Iprograms| file ! | and mapping | j lavailable for | 
l Lrequest {SHARED access | 
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The number of user programs able to have SHARED FILES open, the 
number of SHARED FILES per user, and the total number of SHARED 
FILES supported by the SHARING TASK are restricted only by the 
amount of space available in the SHARING TASK's segment 2 for 
control blocks and mapping areas. 


In this structure, a high degree of protection is automatically 
achieved since: 


1. User programs cannot access the file directly. 


2. File buffers are in the SHARER'S segment 2 and are 
unavailable to any user program. 


The HOLD mechanism in SHARED MODE - The READ HOLD 
function-request is required if a record is to be rewritten or 
deleted. The HOLD mechanism in SHARED MODE is maintained by the 
SHARING TASK. The SHARING TASK allows each user program to HOLD 
one record (in any shared file) through READ HOLD. While this 
record is HELD, no other user may access it with READ HOLD; i.e., 
other READ HOLD requests will be forced to WAIT until the record 
desired is released by the user. 


A HELD record in a file is released (removed from HELD state) 
only when one of the following occurs: 


1. The user (holding the record) issues another READ HOLD 
on any SHARED file 


2. The user issues a REWRITE, DELETE, or START RELEASE on 
this file. 


3. The user CLOSES the file or abnormally terminates 
processing. 


The HOLD mechanism provides lockout on a record basis so _ that 
concurrent requests for the same record can be handled 
correctly. A program should attempt to HOLD records for the 
shortest possible time in order to improve concurrency with other 
users. Extensions to provide a fuller capability for multiple 
record updates are to be added at the SHARING TASK level. 


Additional functions available to the user program in SHARED mode 
are: 


1. START RELEASE - This function is available to 
specifically release a HELD record (or HELD file as 
below). Thus, the general rule for avoiding record 
conflict is that a READ HOLD should be followed by a 
REWRITE, DELETE or START RELEASE as quickly as possible. 


2. START HOLD - This function allows a user to gain 
control of a file for the purpose of modifying several 
records or insuring that the file remains consistent 
While an update is made. It insures that no records 
are HELD by other users. This function naturally 
increases the possibility of forcing other users to 
Wait. The FILE HOLD is removed by START RELEASE. A 
START HOLD is invalid if issued when already holding 
any record or any file. 


The above functions are considered as null operations if issued 
in 10 mode (i.e., at the DMS level). 


The READ KEYED and START KEYED functions in SHARED Mode return 
with FS = 80 if UFBKEYAREA does not point to the key embedded in 
the record. 


Log Files 


A lLog-File is a consecutive file which can be opened in 
SHARED mode. A Log-File has records in variable length or 
compressed format. 


When a consecutive file is opened in SHARED mode, the 
sharer will use an existing Log-File (in EXTEND mode, if found). 
Otherwise, the sharer will create a Log-File with the 
user-supplied file name. When a Log-File is created, the 
compress flag and the record count can be supplied by the user 
program (default record count = 1000). The record size for the 
file (maximum) must be supplied when the file is created. (When 
a Log-File is created by the sharer, file protection class is set 
to blank (any user); Log-Files created by a user program and 
subsequently used in SHARED mode will have normal file protection 
class validation.) 


Multiple users can write records to a Log-File once it is 
opened in SHARED mode. Each record is added at the end of the 
file. The sharer will support more than one Log-File opened at a 
time. Log-Files are accessed as normal consecutive files (with 
variable-length or compressed records) in INPUT, IO, OUTPUT, and 
EXTEND modes. 
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Log-File Special Features: 


1. Recovery Feature - A  Log-File will be opened 
successfully even if it was not closed due to a system crash. 
The recovery is automatic during the next SVC OPEN issued on _ the 
file (in any mode). Both record count and EOF indicator are 
recovered; no message is issued. 


2. Write-Through Feature - Even with recovery, the last 
block of data in the DMS buffer will be lost if the system 
crashes. This can be avoided if a disk write operation is 
performed for every logical record WRITE operation (i.e., the 
Write-Through feature). 


If the first character of the filename = C'@’, then the 
Write-Through feature will be in effect for all writes to that 
file (for OUTPUT, EXTEND, or SHARED mode). 


Read-Only Access In SHARED Mode 


Opening a file for shared update requires full (write) 
access rights. This new feature will allow a user having only 
read-access rights (to a file) to open the file in SHARED mode. 
However, the sharer will flag as invalid any REWRITE, DELETE, or 
WRITE function by that user. (All READ and START functions are 
allowed.) A file status value of 85 is returned if such an 
invalid function is attempted. 


Advanced Sharing (Multiple Resources) 


The current sharing facilities (e.g., READ-HOLD, START 
HOLD-FILE, START RELEASE) will be expanded to support the 
following additional features: 


1. Two hold classes (hold for  update/hold- for 
retrieval) 

2. Explicit resource control by range or list 

3. Extension rights 

4. Timeout option for wait on resource 


These new features will be available using the standard DMS 
START vector and a UFB timeout field (value/exit~address) for 
SHARED mode processing. The features are designed for ease of 
use by the application programmer while providing powerful 
functions and being expandable. A general description of each of 
the features is provided below. These new features apply to both 
indexed files and alternate indexed files opened in SHARED mode. 
These features do not apply at all to log files opened in SHARED 
mode. 


1. Hold For Update / Hold For Retrieval 
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When Hold For Update is used, no other user will be allowed 
to hold the particular resources for either update or retrieval 
until the current holder releases them. Hold For Update is 
always implied when a READ-HOLD function request is issued; in 
this way, the user can then rewrite the record without conflict 
in the shared environment. 


When Hold For Retrieval is used, more than one user is 
allowed to hold the particular resources; however, a file or 
record held for retrieval will not be granted to a user who 
Wishes to hold it for update. Hold for Retrieval is useful when 
a file is to be scanned (for a report for example) and no updates 
are to be made on the file during the time of the operation. 


Switching between the two hold classes is not supported 
under advanced sharing. When a user is ‘explicitly’ holding a 
resource for update, a request to hold that same resource for 
retrieval is always flagged as an invalid function sequence. The 
same is true when a user ‘explicitly’ holding a resource for 
retrieval requests that it be held for update. 


2. Explicit Resource Control By Range Or List 


A resource may be held ‘explicitly’ without extension 
rights by using one of the following function requests: 


START HOLD FILE - Hold the whole file 
START RANGE ~ Hold a range of records (primary key) 


These functions support hold for update or retrieval (set 
by user; default = update). They also support a list option such 
that repeated requests to hold file or range are gathered into a 
list by the sharer; the resources are only obtained (held) when 
the user issues a request to end the list and hold all_ the 
resources in one operation. Thus the list option allows any 
variety of resources within multiple files to be held in one 
operation; since the operation is indivisible with respect to 
other hold requests, deadlock cannot occur. 


The START RANGE request and the list option are discussed 
in detail in the following paragraphs. 


a. The START RANGE Request - this request does not 
affect file position. The request describes a range of primary 
key values by supplying parameters in the UFBKEYAREA and 
UFBGKSIZE. UFBGKSIZE is used to specify the effectve key size of 
the range; a value of zero or a value greater than primary key 
size causes the primary key size to be the effective key size for 
the range. 


If the effective key size is the primary key size, then the 
range contains only one record (since primary keys are unique). 
The following examples illustrate the range specification rules: 
(GK = UGBGKSIZE, PK = primary key size, let key field contain 
"ABCDEFG'). 
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ABCD 


1. PK=7, GK=4 Range = all PK where first 4 chars 
= AB 


2. PK=7, GK=2 Range = all PK where first 2 chars 


When a range is specified, no record may be added within 
that range by a WRITE request from another user. Thus the _ range 
notation is similar to the hold file concept where a range is 
merely a contiguous logical subset (by primary key value) of the 
Whole file. When ranges overlap for the same hold class, the 
largest limits of the range are used. When ranges overlap with 
opposite hold classes, then the last function (which caused the 
overlap) is invalid. 


It is possible and even practical to hold a range which 
contains no records. The number of records within a range does 
not affect the function of the range request or other DMS 
requests. 


b. The List Option - The list modifier bit is 
available with the START HOLD-FILE and START RANGE function 
requests. A value of zero indicates the end of the list (default 
value). A value of 1 indicates that the current hold request 
should be added to any pending hold list for this user. The 
pending hold list will expand until a START function with 
End-Of-List causes all resources in the list to be held. As each 
entry is added to the list, it is checked against the other list 
entries for validity (no overlap of different hold class on the 
same resource) and for compaction (if several entries on the list 
may be combined). The order of the list is never of any 
Significance since all resources on the list must be acquired 
together. 


When a list is pending, it will remain pending until it is 
ended by a START HOLD-FILE or START RANGE with list = 0 (END) or 
until a START-RELEASE (or SVC CLOSE) is issued on any shared file 
by this user. (START RELEASE (ALL) and SVC CLOSE cause _ the 
pending list to be erased). 


All DMS functions other than START (as above) are flagged 
as invalid if issued while a list is pending. 


3. Extension Rights 


Extension rights are requested using the 
START-EXTENSION-RIGHTS function request. In order to avoid the 
possibility of deadlock, only one user at a time may have 
extension rights and a user may not hold any resources when the 
request for extension rights is issued. 


START XRIGHTS may be issued while ‘implicitly’ holding a 


record; in this case, the function is valid and the record is 
automatically released at the beginning of the function request. 
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Extension rights provide the only way a user may acquire 
more resources when already holding resources. When a user has 
extension rights, he may issue READ-HOLD, START HOLD (file) and 
START RANGE in order to accumulate as many resources as desired. 
Each resource request is performed immediately when issued while 
having extension rights (the list option is ignored when 
extension rights are active). 


Immediately after the user has obtained all the desired 
resources, extension rights (only) should be released so that 
another user might acquire these rights. 


4. Timeout Option 


A user-supplied error exit specifically for timeout while 
Waiting for a resource will be provided. A specific file status 
value for timeout will be used and RO will contain the address of 
the function request if the timeout exit is taken (same as 
EODAD/ERRAD exit). , 


Note - File position remains unchanged after a time-out 
exit has been taken (i.e., a READ-NEXT HOLD with time-out could 
be repeated if the record was unavailable when first issued). 


The UFB fields UFBTIME (1 byte for timeout wait period in 
seconds) and UFBTIMEEXIT (user supplied exit address) will be 
available in order to set a time value. Time values will remain 
in effect for all function requests until changed by the 
user-program. A time value = O implies an immediate return 
through the timeout exit if the resource is unavailable (i.e., 
wait zero seconds). If UFBTIMEEXIT (timeout exit address) is 
zero, then no timeout option is to be used (i.e., the program 
will wait as long as required until the desired resource becomes 
available). 


The timeout exit may be taken as a result of any of the following 
DMS functions issued on a file opened in SHARED mode: 


1. READ HOLD (next or by key) 
2. START HOLD-FILE, START RANGE 
3. START XRIGHTS 

4. WRITE 


(The timeout exit would be taken whenever the resource required 
was unavailable within the given time period (UFBTIME) and 
UFBTIMEEXIT was not equal to zero). 


The timeout option should be very useful and easy to use 
for application programmers. Other fields in the UFB have _ been 
provided so that the resource held and the current owner are 
available after a timeout exit has been taken. This information 
allows the application programmer to create an exact message to 
the user whenever a resource is unavailable. For example, a 
message containing primary key value and current owner's initials 
might be: 


“THE JONES RECORD IS BEING USED BY ABB" 
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New UFB fields (SHARED mode) for time-out option: 
(Note - these 3 fields are all set = 0 by SVC OPEN.) 


1. UFBTIME - One-byte wait time in seconds (0 = no 
limit) 

2. UFBTIMEEXIT - Exit address for timeout return 

3. UFBHOLDID - Initials of holder of resource 


When a timeout exit is taken, a file status value of C'70' is 
set. UFBHOLDID is always set. UFBKEYAREA will be set with the 
primary key value of the record in conflict if the function was 
‘READ NEXT HOLD'. For all other functions, UFBKEYAREA is 
unchanged when the timeout exit is taken. 


General Notes 
1. The File-Hold Feature 


A file may be held for retrieval or update by using the 
START HOLD function. Holding a file is a logical concept and is 
not equivalent to holding all the records in the _ file 
individually. When a file is held for retrieval, a WRITE 
function on the file will not be executed until the file is 
released. When a file is held for update, only the user holding 
the file may issue a WRITE (to add a record to the file). When 
holding a file, attempting to hold a range of records within the 
file (in the same hold class)* has no affect. Likewise, a READ 
HOLD issued on a file one holds for update will proceed without 
affecting the hold status on the whole file. (A subsequent 
REWRITE or DELETE would also not affect the hold status on the 
whole file.) 


* If the hold class for the range is different than that for 
the file, the start range function is flagged as an invalid 
function-request. Also, a START HOLD-FILE request would be 
flagged as invalid if issued while holding a range within 
that file of the opposite hold class. 


2. Releasing Resources 


When a record is held for update by issuing a READ-HOLD 
‘function request, the record is said to be held ‘implicitly'. In 
all other cases, a resource record (or file) is said to be held 
‘explicitly'. (If a user holds a file or range and issues a 
valid READ-HOLD, or if a user issues a READ-HOLD function while 
having extension rights, the resource is still considered to be 
held 'explicitly'.) 


If a record is held implicitly, it will be released by any 
one of the following actions: 
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a. Issue REWRITE or DELETE on held record 

b. Issue another READ W/HOLD on a shared file 

c. Issue any START function other than positioning 
d. Issue CLOSE (this file) 

e. Issue WRITE on any shared file 


Case B above must include the automatic release of the 
‘implicitly’ held record before the other record is read with 
hold. For cases A,C,D,E, no resource is held after the request 
completes. By definition, if a record is held ‘implicitly', it 
will be the only resource held by the program at that time. 


If a resource is held ‘explicitly’, it must be explicitly 
released by using START~RELEASE or closing the file. The START 
RELEASE-FILE function is also available; it releases all 
resources within one file only. (Closing a file also causes 
release of the resources in that file only.) 


If a program fails to release an explicitly held resource 
before issuing a READ-HOLD, etc. for another resource, this would 
be flagged as an invalid function (assuming the program did not 
have extension rights). This means that there is never any 
automatic release for an explicitly held resource. 


Detailed Functional Overview - SHARED Mode 


The following function descriptions assume that the user 
program does not have extension rights. 


1. READ HOLD - A READ HOLD involves holding one record for 
update. A READ HOLD may have to wait if the required record is 
held by another user. 


A READ HOLD may be issued when holding no _ resources. In 
this case, the record will be held for update by the user after 
the function-request completes. If a READ HOLD is issued while 
‘implicitly’ holding any record, that record will be 
automatically released at the start of the function request. 


If a READ HOLD is issued while ‘explicitly’ holding one or 
more resources, several situations may occur. If the user is not 
holding the indicated record for update, then the READ-HOLD is an 
invalid function (the user may be holding the whole file (or an 
appropriate range) for update in which case the READ-HOLD is 
valid). If the record is held for retrieval by this user, the 
READ-HOLD is flagged as an invalid function. 


2. REWRITE and DELETE - These functions require that the 
record to be processed be held for update. The record will be 
automatically releasd after the function if the record was held 


‘implicitly'; the record will remain held for update if it was 
held ‘explicitly’. There is never a wait for resource for these 
functions. 
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3. READ NO-HOLD and START For Positioning - These 
functions are not affected by the sharing mechanism. 


4. WRITE Function - A WRITE function may be successfully 
issued when holding no resources. The WRITE function may have to 
wait if the file is held (for retrieval or update) by another 
user; a Wait is also required if the new record would fall within 
the range of records held by another user. 


If a WRITE function is issued while ‘implicitly’ holding a 
record, that record will be automatically released at the start 
of the WRITE function-request. A WRITE function-request will be 
flagged as invalid if it is issued while ‘explicitly’ holding any 
resources (unless the file involved or an appropriate range (held 
for update) is included in those resources). 


Ds Resource Control Commands (START Function) - All 
resource control START commands are valid if issued while holding 
no resources; the user program must wait if the resource request 
conflicts with resources held by other users. 


All resource control START commands cause an automatic 
release of any ‘implicitly’ held record. 


The START HOLD commands (with or without the list option) 
are invalid if issued while ‘explicitly’ holding any resource. 


The START RELEASE (ALL) and the START RELEASE-FILE commands 
are always valid; no operation occurs if no resource can be 
released. 


The following functional descriptions assume the user has 
extension-rights. Under extension rights, the user can 
continually hold more resources; all resources are released along 
with extension rights when the program issues a START RELEASE or 
terminates. 


1. READ HOLD - The READ HOLD function can be used to hold 
records explicitly (for update) while the user has extension 
rights. If the user already holds the record for update (e.g., 
by holding the file or a range containing the record), the record 
remains held within the larger group and the READ HOLD is 
successful. If the user holds the record for retrieval, the READ 
HOLD request is flagged as an invalid function. The user may 
have to wait if the record is held by another user. 


2. REWRITE and DELETE Functions - These functions must be 
issued on a_ record which is held for update. When the user has 
extension rights, there is no ‘automatic release’ on the record 
after a REWRITE or DELETE (i.e., the record was held explicitly). 


3. WRITE Function - The WRITE function may be issued at 
any time if the user has extension rights; the only error 
condition results if the file (or record range) is held for 
retrieval by the user. 
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4. Resource Control Commands (START Function) - These 
commands can be issued while having extension rights. 
Overlapping requests are handled such that more resources may be 
obtained; requests for records already held have no effect if the 
hold class agrees. Any request which would require changing a 
hold class for resources already held by this user is flagged as 
invalid (i.e., changing between update and retrieval classes is 
not supported). The START EXTENSION-RIGHTS command is also 
flagged as invalid if issued when the user already has those 
rights. 


Summary Of START Functions ('#' Indicates New Feature) 


START EQUAL, START EQUAL OR GREATER, and START GREATER THAN 
positioning functions are unchanged. 


START HOLD (80) Hold file for update 

START HOLD RETRIEVAL (CO)  # Hold file for retrieval 

START RANGE (84) # Hold range for update 

START RANGE RETRIEVAL (C4) # Hold range for retrieval 

(The 4 functions above have the list option also (10) .) 

START RELEASE (20) Release all resources (this 
user) 

START RELEASE FILE (24) # Release all resources in 
this file 

START RELEASE XRIGHTS (21) # Release Xrights only 

START HOLD XRIGHTS (81) # Obtain extensions rights 


UFB Field Updates 


The new fields UFBTIME, UFBTIMEEXIT, and UFBHOLDID will be added 
for SHARED mode only. 


The following equated values will also be added: 
START modifier bits indexed files - 
Existing values remaining unchanged are UFBVEQ (01) , UFBVGT (02) 


and UFBVGE (03). The following two values are unchanged although 
their meaning is slightly altered. 


UFBVHFILE (80) | - START function = HOLD 

UFBVRLS (20) START function = RELEASE 

New Values: 

UFBVRANGE (04) Request is for a range 

UFBVRETRIEVAL (40) Hold class = retrieval if set 

UFBVXRTS (01) Extension rights for hold/RLS 

UFBVLIST (10) List option (hold range or 
file) 
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New File Status Values: 
UFBFS1TIME EQU C'7' 


UFBFS1SHARE EQU C'8' 


UFBFS2ACC EQU C'5' 


UFBFS2RESERR EQU C'6' 


FS value for time-out on 


resource 

FS class for sharer 
conditions 

Update access denied 


(FS=C'85') for user with 
read-only rights in SHARED 
mode 

Resource control error 
(FS=C'86') 


In using FS=86 for all invalid resource control commands, some 
FS=95 should be updated. FS=95 for record not held would remain 
valid for IO mode; however, for SHARED mode this case would be 


changed so that FS = 86 was used. 
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7.5 DMS FUNCTION-REQUESTS 


This section contains a brief list of the UFB values used by 
DMS. An _ extensive list of all DMS filestatus conditions is also 
included, along with a description of the various DMS error 
returns. 


7.5.1 DMS Function-Request Entry 


The performance of a DMS function-request on a file is effected 
by calling a DMS (function-request) routine. The DMS routine 
addresses are available in the UFB (after OPEN). The DMS 
routines define the access method to be used in processing the 
file; functions not supported for a particular filetype OPEN mode 
combination are indicated by a DMS routine address (in the UFB) 
which returns an INVALID FUNCTION error indication. 


DMS routines are entered using the CALL macroinstruction (JSCI) 
with the following registers loaded: 


a. R1 - UFB pointer 
b. R15 - Stack pointer (updated by CALL) 


Several standard operations are taken at the start of all DMS 
routines. | 


a. Establish addressability, etc. 


b. Verify that the file has been opened by checking that 
OFBUFB (UFB pointer from indicated OFB) equals UFB 
pointer in Rl. (This check insures that a valid OFB 
exists. Failure will cause a 'fatal error' with a 
meaningful error indication.) The OPEN Mode 
(processing mode) is established through OFBFLAGS. 


The following UFB fields are generally used during a function- 
request. The specific UFB fields per function-request are 


described later. 


i. 


iv. 


vi. 


vii. 


viii. 


ix. 


UFBOFB - Pointer to OFB for this UFB. 


Modifier byte from function vector - used by some 
DMS routines. 


UFBRECSIZE - Length in bytes used for all record 
movement and for maintaining the sequential 
record pointer (SRP). 


UFBBUFDATAL ~- Length in bytes for physical I/O 
data transfer. 


UFBRECAREA - Pointer to user-record-area (loaded 
from UFB for each function-request) . 


UFBBCBFLAGS, UFBBUFOFFSET - buffer control 
information. 
UFBEODAD, UFBERRAD - _ Error and exceptional 


condition exit address (loaded from UFB as 
required) . 


UFBFS1, UFBFS2 - File Status (bytes) set by all 
DMS routines on return. 


UFBLF - Last function on file, loaded by each DMS 
routine (also UFBLFMOD - last modifier byte). 


UFBKEYAREA ~ Pointer to user supplied key or 
relative record number. 


Common UFB Input Parameters - Available for all consecutive disk 


file operations. 


UFBEODAD (May be supplied by user prior 
UFBERRAD to function-request) 

UFBLF 

UFBLFMOD 

UFBBUFSIZE 


The following UFB fields are used as 16-bit positive numbers 
rather than halfwords (15 bits and sign). These fields are used 
only by DMS for most cases: UFBBLKSIZE, UFBBUFSIZE, UFBCHKSIZE, 
UFBBUFDATAL, UFBBUFSIZE, and UFBMAXTFR. 
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7.5.2 DMS Function-Request Return 


DMS returns to the user program using the RETURN macro- 
instruction. User registers 2 through 15 are always’ restored. 
Register 0 (RO) is restored unless UFBEODAD or UFBERRAD is used 
-- RO then contains the normal return address. Register 1 (R1) 
is restored unless the Read-No-Data option has been used, in 
which case Rl contains the record address. 


DMS indicates the result of the function-request through the file 
status bytes UFBFS1 and UFBFS2. These bytes generally contain a 
value of X'30' - X'39' corresponding to the ASCII characters 0O 
through 9. This value is called the File Status (FS) Code. 
Refer to Appendix C for a list of the DMS and ADMS File Status 
Codes. 


Return Address Usage (Return to User-Program) 


Ae Normal return - The RETURN instruction causes 
registers to be restored and the program 
continues at the instruction after the DMS call. 


as UFBEODAD return (UFBEODAD not = 0) - The address 
in UFBEODAD is used. The program continues at 
this address; file status is set to the 
appropriate value and RO = the normal returm 
address.* 


3. UFBEODAD return (UFBEODAD = 0 and UFBERRAD not — 
0) In this case, the address in UFBERRAD is 
used. The program continues at this address; 


file status is set and RO = the normal return 
address.* 
4. UFBERRAD return (UFBERRAD not = 0) - The address 


in UFBERRAD is used. Before returning to _ the 
program, an acknowledge-type GETPARM message is 
issued by DMS. This message indicates the UFB 
address, the DMS function-request address, the 
file status value and a brief description of the 
significance of the file status. The user may 
continue or CANCEL at this point. If the program 
is continued, return is made to the address in 
UFBERRAD with file status set and RO = the normal 
return address.“ If UFBF4NOACK is set, the 
acknowledge message is not issued and return is 
made using UFBERRAD. 


* ~ The high-order byte of RO is set to zero 
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DMS Fatal Errors 


A fatal error causes DMS to issue an SVC CANCEL. The CANCEL 
message describes the situation and gives the UFB address, 
function-request address and PRNAME- of the file. The 
user-program cannot be continued after a CANCEL is issued. 


1. Fatal errors for file status error conditions - If 
UFBERRAD is zero (for file-status greater than or equal 
to C'30') or if both UFBEODAD and UFBERRAD are zero 
(for file-status less than C'30'), then the user has 
not supplied a return address for file-status error 
conditions. In this case, the CANCEL message will 
include the file status value and a description of the 
file status significance. 


2. Other fatal errors - In the course of performing a 
function-request, DMS uses several UFB fields. If any 
of these fields is inconsistent or invalid, DMS will 
recognize this and CANCEL the program. The CANCEL 
message will indicate which field had the invalid 
value. These errors are generally caused by the 
user-program incorrectly modifying DMS fields in the 
UFB. 


3. Program check during DMS function-request - If a 
program check occurs in DMS, the most likely reason is 
an invalid address in UFBRECAREA or UFBKEYAREA. (These 
fields are not checked since the general DMS 
requirement is efficiency.) A program check in DMS can 
be identified by inspecting the save area trace 
(available as a debugging command in HELP); register Rl 
in the DMS save area contains the UFB address. 


7.6 PRINTER SUPPORT 


Records output to a printer file are variable-length (P-type) 
records as described in Section 4.2.1. Data may be written to a 
printer using either the Record Access Method (RAM) or the 
Phsyical Access Method (PAM). The Write function-request under 
RAM is described in this section. The Physical Access Method (as 
described in Section 4.8) is available to write a block of P-type 
records to a printer. 


The user program views a printer file as an output-only file 
containing an unlimited number of variable-length records. A 
printer file record contains a 2~byte user-supplied control field 
and a variable number of data characters (depending on record 
size). DMS routines are available to write a user record to _ the 
printer file. The maximum record size for the file is 
established by the value of UFBRECSITE at SVC OPEN. File Status 
= ‘'97' (invalid length) is returned if the value of UFBRECSITE 
for a function-request exceeds this value. 
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A printer file always has UFBFORGPRINT set. (This implies that 
the user program has supplied the 2-byte printer control field as 
part of the record*.) UFBBUFDATAL (length used for physical I/0) 
is set from UFBRECSIZE. (UFBBUFDATAL is maximum 134 fora 
printer file using RAM.) For expanded characters, the device 
will truncate any line after 68 characters; no error reported. 


The only valid OPEN mode for a printer file is OUTPUT mode. The 

only valid function-request for a printer file is WRITE. 

% If UFBFORGPRINT is set for a disk file, a consecutive file 
with variable-length compressed records is created. A _ large 
buffer size may be set for a printer file prior to SVC OPEN. 
This buffer size will have no effect if the output is 
directed to a printer. However, if the sequential output is 
directed to a disk file, the large buffer will result in 
fewer physical I/0 operations. 


7.6.1 Write Function-Request (OUTPUT) 


Inputs: a. Common UFB Input Parameters 


b. UFBRECAREA - Location of the user record area (any 
Segment 2 address). 

c. UFBRECSIZE - Length of record. This length is 
moved to UFBBUFDATAL for each Write 


function-request. 


DMS routine operations: The record (as indicated by UFBRECAREA 
and UFBBUFDATAL) is moved to a protected buffer (by SVC 
XIO) and then the printer I/0 write operation is 
initiated. The operation is waited on (at the DMS 
level) before the next record is moved to the buffer. 
(The modifier byte is ignored.) Trailing blanks are 
stripped from the record by DMS before calling SVC XIO. 


Since the file has been successfully opened there are 
no (1/0) error conditions returned to the user other 
than invalid length or invalid command (FS='96' or 
'97'). (Out-of-paper, deselected, power-off, or device 
not operational are handled by SVC XIO.) 


Outputs: UFBFS1, UFBFS2 stored in UFB. 
Record written to printer file. 
UFBLF is set to indicate WRITE. 


7.7 WORKSTATION SUPPORT 


A workstation on the 2200VS system is defined as a CRT and a 
keyboard. All workstation processing by DMS is performed under 
the Record Access Method (RAM) in IO mode. 


The user program views a workstation file as an interactive file 
containing a fixed number of records (i.e., CRT rows) of a fixed 
maximum length (i.e., CRT columns). A workstation record (in the 
user~record-area) contains a 4-byte order-area followed by a 
variable number of data characters (mapping area). Workstation 
records are written to the CRT by the user program. The user 
program can read CRT records which can be modified by the 
workstation operator (through the keyboard). 


UFBBUFDATAL (length used for physical 10) is set from 
UFBRECSIZE. Workstation Read or Rewrite operations are performed 
directly on the record area in Segment 2. The record area must 
be word aligned; otherwise, File Status indicating the error will 
be returned. Each workstation has an associated unit control 
block (UCB) which contains the ‘current’ AID character and 
keyboard status (locked or unlocked). 


A workstation file can only be OPENED in I0 8} £Mode. The 
function-requests available are READ, REWRITE, and START. 


An order check is returned as C'34'. An order check is detected 
by examining the IOSW; however, it is not considered an I/O error 


for logging purposes. (Power-off, deselected or device not 
operational are handled by SVC XIO.) Other error conditions are 
incorrect length and record area not aligned (File Status = '97' 


and '96' respectively). 


The input for workstation function-requests is the common UFB 
(workstation) Input Parameters. This includes the Common UFB 
Input Parameters, UFBRECAREA (an address pointing to the 
user-record-area), and UFBKEYAREA for address of word containing 
the Relative Record number (i.e., row number, not used for START 
function-request) . 


Workstation operations use UFBRECSIZE as the length of the 
record. UFBRECSIZE less than 4 results in the Order Check error 
condition. The user may set UFBRECSIZE before any 
function-request. UFBRECSIZE is moved to UFBBUFDATAL by the DMS 
vector routine before initiating the physical I/O operation. 


7.7.1 Read Function-Request (1/0) 


Inputs: 


a. Common UFB (WS) Input Parameters 
b. Modifier byte at UFBVREAD 
MODIFIABLE option 
TABS option (nonCOBOL) 
c. UFBRECSIZE - Length of record 


DMS routine operations: The relative record number (at the word 


pointed to by UFBKEYAREA) is moved to the first byte of 
the order area. (RRN other than 124 causes an order 
check return to the issuer.) If UFBKEYAREA=0, the row 
number already in the order area is left unchanged. 
The DMS routine then calls SVC XIO to initiate the read 
I/O operation (the modifier byte is reflected in the 
command byte sent to SVC XIO). SVC XIO will issue the 
command when the keyboard is locked (or when it becomes 
locked through operator action). After the wait for 
I/O completion, the following information is available: 


a. The record (at order area +4) is available in the 
user-record-area. 


b. Order area bytes 2-3 in the user-record~area 
receive the current cursor position. 


c. UFBFS2 receives the AID character (from the UCB). 


MODIFIABLE option* - This option causes the following 
actions: 


a. The modifiable fields within the record are _ loaded 
from the corresponding workstation CRT positions. 


b. Protected fields within the record are either 
skipped (leaving those relative locations within 
the user-record-area unchanged) or moved from the 
workstation to the user-record-area (depending on 
workstation model). In the later case, the 
protected fields will receive the characters 
present when that line was last written to the 
screen, 


c. Pseudo~blank characters on the screen are changed 
to blanks before transmission; therefore, they are 
also represented as blanks within the 
user~record-area. 


d. Blinking characters within the range of the READ 
operation will be changed to high-intensity 
nonblinking characters (by changing the associated 
field attribute character both on the screen and in 
the user's record area). 
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Outputs: 


e. Order area bytes 2-3 in the user-record-area receive 
the current cursor position. 


f. UFBFS2 receives the AID character (from the UCB). 


UFBFS1 stored. 

UFBFS2 stored (equal AID character). 

Order check (UFBFS1, UFBFS2 = 34) is a possible 
exception (return through UFBERRAD, no logging of ‘I/O 
error'). 


Record is available in user-record-area. 
UFBLF, UFBLFMOD set. 


(Keyboard is locked.) 


* The recommended sequence of workstation 


function-requests involves Read Modifiable rather than 
Read. 


Recommended sequence (one user-record-area) 
1. Rewrite record to workstation. 


2. Read modifiable; data entered by workstation 
operator is now available in the user-record-area. 


3. The user-program may change fields within the 
user-record-area based on the data received. 


4. Rewrite record to workstation (for additional 
information, error correction (reentry), etc.). 


It is important to note that protected fields within the 
user-record-area should be changed after the Read 
Modifiable function-request (rather than before the Read 
Modifiable function-request) . 


7.7.2 Rewrite Function-Request (1/0) 


Inputs: 


a. Common UFB (WS) Input Parameters 

b. Modifier byte at UFBVREWRITE 
TABS option (nonCOBOL) 

c. UFBRECSIZE - Length of record 


DMS routine operations: The relative record number (at UFBKEYAREA, 


indicating row number) is moved to the first byte of the 
order area (user-record-area). (RRN greater than 24 
causes an order check return to user.) If UFBKEYAREA=0, 
the row number already in the order area is left 
unchanged. The second byte of the order area is a 
user-supplied Write Control Character (WCC); the third 
byte is a user-supplied column number (for optional 
cursor positioning); these bytes are not used by the DMS 
routine. . 
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The DMS routine initiates the physical I/O write 
operation and waits for completion. After completion, 
the DMS routine returns control to the user-program. 


Outputs: UFBFS1, UFBFS2 set for operation successful. 
(Order check is also possible.) 


The workstation record is written (including actions 
directed by the WCC). UFBLF, UFBLFMOD are set. 


7.7.3 Start Function-Request (1/0) 


Inputs: Common UFB (WS) Input Parameters 


DMS routine operations: The DMS routine inspects the UCB for the 
current state of the workstation; it then sets the file 
status bytes accordingly. 


UFBFS1 = C'0' - Operation successful 

UFBFS2 = AID character - If AID character = blank, then 
the keyboard is unlocked; otherwise, the keyboard is 
locked and UFBFS2 = current AID character. 


(The Start function-request can be issued (prior to a 
Read function-request) to determine whether a 
subsequent Read function-request would wait (for 
keyboard to be locked) or would process immediately.) 


Outputs: UFBFS1, UFBFS2 set 
UFBLF, UFBLFMOD set. 


7.8 MAGNETIC TAPE SUPPORT 


Wang magnetic tapes are processed through the Data Management 
System, using OPEN, DMS functions, and CLOSE. 


Two tape densities, 800 and 1600 BPI, are supported. At tape 
mount, a physical I/O will test the tape density and indicate it 
in the UCB Tape Density Field. At OPEN, the density will be 
checked against the user-specified value. 


Tape labels supported in the first release are ANSI-Label (AL), 
IBM-Label (IL), and No-Label (NL). They are described in our 
Tape Label Control Blocks. Tape labels are written in ASCII code 
for AL, and EBCDIC for IL. Tape data structure and labels are 
compatible with the industry standard (see the IBM OS Tape 
Manual, for example), with the following restriction and 
extensions: 


(1) The label-handling routines will always skip existing User 


Header and Trailer labels, and will not create them on new 
tape files. 
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(2) Only 80-byte labels are accepted. 


(3) Five kinds of record formats are supported: 


'F' - fixed-length format 

‘v' ~- variable-length IBM format 
‘w' - variable-length Wang format 
'X' - compressed Wang format 

‘U' -  undefined-length format 


Tape data blocks of format 'W' and ‘'X' are to contain a 
block length prefix (like the corresponding disk blocks) in 
order that short blocks (less than 18 bytes) can be padded 
to prevent their being interpreted as 'noise' blocks. 


Tape files in ‘V' format have IBM variable-length record 
blocking format. Short blocks are padded, as above, if 
less than 18 bytes long. 


For '‘'U' format files, each block is considered as a 
record. Short 'U' format blocks are never padded. 


Receipt of a block of less than 12 bytes (in INPUT mode) is 
treated as a length error. 


(4) Minimum block size is 12 bytes for INPUT, and 18 bytes for 
OUTPUT. 


(5) For IBM-label tape, EXTEND mode is not supported. 


Tape files may be positioned by file-sequence number. The 
program specifies file sequence in UFBISEQ before opening the 
file. For NL tape, each file is separated by tape marks. For an 
existing labelled tape file being opened in INPUT or EXTEND mode, 
positioning can also be done by library and file names (see 
below). 


The Wang Data Management System supports tape access in INPUT, 
OUTPUT, and EXTEND modes, through the RAM, BAM, and PAM access 
methods. CLOSE allows a user to rewind, rewind and unload, or 
not rewind the tape. 


For an existing labelled tape file, DMS will use label 
information to determine the buffer size. For a new tape file or 
NL tape file, the program must supply the buffer size in 
UFBBLKSIZE. 


Multiple-volume tape files are also supported in this release. 
Double buffering is always used for tape 1/0 processing. 


7.8.1 Mount/Dismount a Tape 
Tape can be mounted through the 'MOUNT' command or during 


‘OPEN'. The MOUNT SVC and command are described elsewhere and 
Will not be repeated here. 
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The tape drive density is set to 1600 BPI for 
bypass-label-processing (BLP) type mount, and set to the physical 
tape density for normal mount. 


If the tape volume is not found at OPEN, the OPEN SVC will issue 
a respecification message directing the user to mount the tape 
volume, much like the disk mount respecification. The only 
difference is that tape mount through OPEN is always for 
Exclusive use. 


A tape volume mounted for SHARED use can be opened by all _ users. 
However, once the tape is opened, it will become mounted for 
Exclusive use and will remain so until remount or dismount. 


To dismount a tape, the DISMOUNT SVC must be used or the file 
must be CLOSEd with Rewind~And-Unload specified. 


7.8.2 Initialize a Tape Volume 


The VS utility program TAPEINIT is used to initialize a new 
labelled volume. TAPEINIT first mounts the new tape using BLP 
option. The MOUNT SVC positions the tape at the Load Point 
Marker, and sets the Label Type to UNLABELLED. TAPEINIT then 
opens the NL tape in OUTPUT mode with File Sequence Number 1, and 
with Tape Density chosen. OPEN sets the drive density, and 
writes the VOL] LABEL (in ASCII for ANSI label and EBCDIC for IBM 
label). At CLOSE, two tape marks are written by the CLOSE SVC to 
indicate that no file is on the tape. TAPEINIT then uses the 
Mount With No-Message option to tell the system the new tape 
volume name and its label type. 


7.8.3 Open a Tape File 
Input to OPEN SVC includes the following UFB fields: 


UFBBLKSIZE (Tape Block Size): 


For NL Tape, UFBBLKSIZE is the maximum block size 
of the tape file. 


For labelled tape, .VFBBLKSIZE is interpreted 
differently for different OPEN modes. In OUTPUT 
mode, it is the maximum block size of the _ tape 
file, and is the block size recorded in the tape 
label. In EXTEND mode for all access methods or in 
INPUT mode using BAM or PAM, UFBBLKSIZE is the 
maximum block size acceptable, unless it is set to 
0, meaning that the maximum block is size 
unknown. 


Maximum size is 32K in all cases. Minimum size is 
12 bytes for existing files, 18 bytes for new files. 
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UFBRECSIZE (Tape Record Size): 


UFBFORG: 


UFBF1: 


UFBF2: 


UFBDEVCLASS: 


UFBFLAGS : 


UFBPRNAME : 


UFBVOLSER: 


Ignored in BAM or PAM. In RAM, UFBRECSIZE is used 
as follows: for NL tape with fixed-length records 
specified, UFBRECSIZE is the record size expected. 
For NL tape with variable-length or undefined- 
length records, it is the maximum record size 
expected. For labelled tape (AL/IL) in OUTPUT 
mode, it is the record size to be recorded in the 
label. For labelled tape in INPUT mode, it is the 
maximum record size acceptable, unless it is set to 
0, meaning that the maximum record size is 
unknown. For labelled tape in EXTEND mode, 
UFBRECSIZE is ignored. Tape record size must be 
less than or equal to BLKSIZE (no record may span 
two or more blocks). For RAM with fixed-length 
records, the UFB is considered to be in error if 
BLKSIZE is not a multiple of RECSIZE. 


Maximum record size in 32K in all cases. 


Indexed files are not supported. If UFBFORGVLEN is 
set, OPEN will accept a variable-length record 
format (W-format) tape file only. If UFBFORGU is 
set, OPEN will accept an undefined record format 
(U-format) tape file only. If UFBFORGVIBM is set, 
OPEN will accept an IBM variable-length record 
format (V-format) tape file only. If none of the 
above flags is set, OPEN will cancel the program 
with an error indicator. 


All options are supported. 


For AL and NL tapes, INPUT, OUTPUT, and EXTEND 
modes are supported. For IL tapes, only INPUT and 
OUTPUT modes are supported. PAM in EXTEND mode is 
not supported. 


Set to X'02' to indicate tape (but see UFBF4ALLOWT, 
below) . 


Only the 'COMPRESS* option is used. 

OPEN prname. 

Tape volume name. If the volume is not found, OPEN 
will either display a respecification message to 


request that the tape volume be mounted or take the 
specified OPEN Exit. 


UFBFILENAME 
and 
UFBDIRNAME: 


UFBF4: 


UFBTLABELS: 


UFBTDEN: 


UFBTSEQ: 


The library name and file name are ignored for NL 
tape. For AL or IL tape, they must be specified 
in OUTPUT mode. In these cases, the specified 
names are entered into the tape label in the form 
‘library.file' (for example, YKW.TEST). For IL 
tape, translation to EBCDIC is performed. For an 
existing labelled file, if file sequence is 
supplied in UFBTSEQ, UFBFILENAME and UFBDIRNAME are 
nonblank and OPEN uses the library and file names 
to position the tape. The tape file name in the 
HDR1 is decoded according to the format 
‘library.file', and will be treated as_ blank 
otherwise. If the file sequence is supplied, OPEN 
positions the tape by File Sequence Number and then 
checks the file name (if nonblank) against the file 
label. File and library names in IL labels are 
translated to ASCII for comparison with the 
corresponding UFB fields. 


UFBF4NOMSG and UFBF4ALLOWT are used. In order to 
open a tape file, either UFBDEVCLASS must indicate 
'TAPE' (X'02) before OPEN, or UFBF4ALLOWT must be 
set. 


Tape label type (NL,AL,IL,ANY). If ANY is 
specified, OPEN will allow any label type _ tape 
file. If more than one type is specified, OPEN 
will accept tape files with the specified label 
types. 


Tape density (800 BPI, 1600 BPI). If UFBTDEN is 
set to binary zeroes (tape density not specified), 
OPEN will set the UFBTDEN to the density found in 
the UCB. If UFBTDEN is specified, and the _ tape 
volume is not mounted for "Bypass Label Processing" 
(BLP), OPEN will check the UFBTDEN against’ the 
actual tape density, and will respecify or take the 
OPEN Exit if they do agree. If BLP is in use, the 
tape drive density will be set to the density 
according to UFBTDEN, and will be recorded in the 
UCB. 


File sequence number. OPEN uses this number to 
position the tape. It must be specified for NL 
tape and for labelled tape in OUTPUT mode. For 
existing files on a labelled tape, one can also 
position by file name. 
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OPEN EXIT 
FLAGS: | 


Tape OPEN Exits are handled exactly as disk OPEN 
Exits. The OPEN Exit masks are set up in the first 
byte on the top of the stack in the SVC input 
parameter. Currently supported OPEN Exits are: 


(1) Volume not found 

(2) File not found, or sequence number out of range 

(3) No space available on tape volume to create new 
file 

(4) Possession conflict 

(5) Wrong label type or wrong density 


No other fields in the UFB are used as ‘OPEN’ input. 


Output of the OPEN SVC includes the following UFB fields: 


UFBVREAD 
and 
UFBVSTART: 


UFBFS1 
and 
UFBFS2: 


UFBBLKSIZE: 


UFBRECSIZE: 


UFBFORG: 


UFBFLAGS: 


UFBF1: 


Set to DMS routine entry address. 


Set to OPEN Return Code. If UFBF4NOMSG is 

requested and OPEN is not successful, a 4-byte 
message ID is set at the beginning of the UFB, just 
as for Disk OPEN. If OPEN Exits are set, UFBFS2 is 
the exit flag. (The exit flag indicates which OPEN 
Exit condition is taken, just as for Disk OPEN 
Exit.) 


For labelled tape, existing file (INPUT and EXTEND 
mode), UFBBLKSIZE is set to the tape block size 
from the file label. This is the maximum allowable 
block size for DMS operations. 


For an existing file on labelled tape, (INPUT and 
EXTEND modes), using RAM, UFBRECSIZE is set to the 
record size from the file label, and is the maximum 
acceptable record size for DMS operations. For an 
existing file on labelled tape, using RAM with 
undefined record format, it is set to the block 
size from the tape label, and is the maximum 
acceptable record size for DMS. 


Set to actual tape file organization in INPUT and 
EXTEND modes. 


Compress flag set for an "X" format file in INPUT 


and EXTEND modes. 


UFBF1PREVO and UFBFIOPEN flags are set. 
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UFBDEVADDR: Set to the device number of the device on which the 
tape volume is mounted. 


UFBFILENAME For a labelled tape in INPUT and EXTEND modes, OPEN 

and will decode the tape file name in the HDR1 and put 

UFBDIRNAME: it in these fields. The name in the label must be 
in the form 'library.file’ in order to be decoded. 
Otherwise, these fields are left blank. 


UFBNRECS: Set to 0. 
UFBLRECSAVE: Set to the same value as that in UFBRECSIZE. 


UFBTLABELS: Will be set to the actual tape label type after 
successful OPEN. 


UFBTDEN: Will be set to the actual tape density after 
successful OPEN. 


UFBTSEQ: Will be set to the tape file sequence number after 
successful OPEN. 


UFB fields in the DMS section are initialized. No other fields 
are used. 


OPEN SVC functions - Existing File (INPUT and EXTEND Modes): 


OPEN issues a 'GETPARM' to obtain the volume name, file mame, and 
file sequence number. If the volume is not mounted, a message is 
displayed requesting the user to mount the volume. The tape is 
then positioned by file sequence number or file name. 
Information in the file label (for labelled tape) is then 
extracted and placed in UFB fields and control blocks are 
allocated. UFB fields are initialized and the tape positioned to 
the first data block for INPUT mode to the tape mark following 
the last data block for EXTEND mode. Two I/O buffers of the size 
specified in UFBBLKSIZE are allocated in the Segment 2 buffer 
area. 
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OPEN SVC Functions - New File (OUTPUT MODE): 


OPEN issues a 'GETPARM' to obtain the volume name, file name, and 
file sequence number. If the volume is not mounted, a message is 
displayed requesting the user to mount the volume. The tape is 
then positioned by file sequence number. For labelled tape, the 
file labels HDR1 and HDR2 are constructed and written on the tape 
(and followed by a tape mark). Library and file names are 
converted to the form (lib.file) and placed in the HDR1 file. 
(No labels are written for NL tape.) Control blocks are 
allocated. UFB fields are initialized, and the tape is 
positioned to the first data block. Two buffers are allocated 
(as for INPUT mode). 


7.8.4 READ Function Request 


INPUTS: The following UFB fields are used: 
UFBEODAD, 
UFBERRAD: Error Exit address. 


UFBVREAD: Function modifier. 


UFBRECAREA: Record area for the record read. 


Outputs: The following UFB fields are set: 
UFBFS1, 
UFBFS2: File status after DMS functions. 


UFBRECSIZE: Set to record size after READ in RAM. 


Set to block size after READ in BAM. For "U" 
format file, in RAM, RECSIZE is the block size of 
the block which was read. 


UFBNRECS: Number of records processed. 


DMS Routine The next record on the tape file is moved to 

Operations: user-specified record area. For multiple-volume 
tape files, volume switching may be performed (see 
7.8.8 below). If the NODATA option is used, the 
record is not moved to the record area. Instead, 
the record pointer is returned in general 
register 1. 


7.8.5 WRITE Function-Request 


Inputs; 
UFBEODAD 
and 
UFBERRAD: 
UFBRECAREA: 
UFBBLKSIZE: 


UFBRECSIZE: 


Outputs: 


UFBFS1, 
UFBFS2: 


UFBNRECS: 


DMS Routine 
Operations: 


The following UFB fields are used: 


Error Exit address. 

Record area of the record to be written. 
Tape block size to be written. (Used in PAM only.) 
Record size, specified when writing records for 
variable-length-record files (record formats V, W, 
X, and U). 


The following UFB fields are set: 


File status after DMS functions. 
Number of records processed. 
The record addressed by UFBRECAREA is written to 


the tape. For multiple-volume tape files, volume 
switching may be performed (see 7.8.8 below). 


7.8.6 START Function-Request 


Inputs: 


UFBEODAD, 
UFBERRAD: 


Outputs: 


UFBFS1, 
UFBFS2: 


DMS Routine 
Operations: 


The following UFB fields are used: 


Error Exit address. 


The following UFB fields are set: 
File status after DMS functions. 


To wait for the completion of a previous READ/WRITE 
request (in PAM only). 
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7.8.7 Close Tape File 


Inputs: UFB fields used by CLOSE: 

All UFB fields left from previous DMS functions will be used by 
CLOSE. No unauthorized modifications should be made to the UFB. 
Options supported are "NOREWIND', 'UNLOAD', and ‘REEL'. 


Output: UFB fields used by CLOSE: 


UFBFS1, 

UFBFS2: Return Code. 

UFBF1: UFBFIOPEN flag turned off 

CLOSE In OUTPUT and EXTEND modes, CLOSE writes out data 
SVC in buffers. For labelled tape, the trailer labels 
Functions: EOF1 and EOF2 are constructed and written to tape, 


followed by two tape marks. For NL tape, only two 
tape marks are written; trailer labels are 
written. In INPUT Mode, CLOSE completes the last 
1/0 operation. CLOSE then deallocates control 
blocks and buffers, cleans up UFB fields, rewinds 
the tape, and returns unless the ‘NOREWIND' or 
‘UNLOAD! options are specified. For the ‘NOREWIND' 
option, CLOSE positions the tape to the tape mark 
following the processed tape file, rather than 
rewinding it. For the 'UNLOAD' option, the tape is 
rewound, unloaded, and logically dismounted. 


The 'REEL' option asks CLOSE to terminate the 
current volume with an 'End Of Volume’ label and 
continue the tape file on next volume (see 7.8.8 
Multiple-Volume Tape File, below). 


7.8.8 Multiple-Volume Tape File 


The multiple volume tape processing is supported by DMS for AL 
and IL tape files, as described below. 


To Read a Multiple-Volume Tape File (INPUT Mode) 


When end-of-tape is reached, DMS reads the trailer label (if 
neither EOF1l nor EOV1 is found, a warning message will be 
displayed, and the End-Of-Data exit will be taken), compares’ the 
tape block count with the actual number of tape blocks read, and 
warns the user if the counts are inconsistent. 


If the trailer label is an EOF1 block (indicating end-of-file 
reached) , the End-Of-Data exit is taken with File-Status = 10. 


If the trailer label is an EOV1 block (indicating file to be 
continued to next volume), and if the user has specified the 
NOMSG option or EOD=EOV option, the End-of-Data Exit is taken 
with File-Status = 11. 


Otherwise, the tape file is continued to the next volume. A 
volume switch message is displayed, directing the user to mount 
the next volume. The newly mounted volume is checked for the 
correct volume sequence number and the 'READ' operation continues 
from the new volume. 


To Create a Multiple-Volume Tape File (OUTPUT Mode) 


When end-of-tape is reached, DMS checks the NOMSG flag and EOD = 
EOV flag. If either of these flags is set, the Boundary 
Violation Exit is taken with File-Status = 34. Otherwise, the 
EOV1 and EOQV2 blocks are written on the tape followed by two tape 
marks, and DMS displays a message asking the user to specify the 
next volume and device. A MOUNT SVC is issued asking the user to 
mount the next volume and the WRITE operation continues on _ the 
next volume. 


7.8.9 7-Track Tape Support 


The 7-track tape records only six bits of data for each byte. 
Thus, only the six low-order bits of each byte are written on 
tape and, during a read, the two high-order bits are set to zeros 
in main memory. 


Data can be recorded on the tape using odd or even parity. Note, 
however, that a data pattern of X'00' cannot be recorded on tape 
with even parity; instead, it is recorded as X'OA'. If it is 
recorded with odd parity, it is recorded as X'00'. 


Data Management supports only unlabelled tape files for 7-track 
tape. The tape mount function is the same as for 9-track tape; 

tape density is set to 800 bpi (the only density supported). 
System control blocks always indicate label type ‘NL’. 


When opening a /7-track tape file, the user must specify the 
parity of the file in UFBTPARITY, even for an existing file. All 
other UFB fields are used as for 9-track tape. In RAM, only 
fixed-length and undefined-length records can be used for 7-track 
tape. BAM and PAM are supported as for 9-track tape. 


All DMS’ functions as well as CLOSE are then same as four 9-track 
tape. 


71-64 


7.9 PHYSICAL ACCESS METHOD FUNCTIONS 


Any disk file can be accessed under the Physical Access Method 
(PAM) when UFBFIPAM is set in the UFB (at OPEN.) In this case, 
the file is the accessed by block number (from zero) rather than 
record number. SVC OPEN does not allocate I1/0 buffers when 
UFBFIPAM is set. All I/O is performed by reading or writing 
directly from a user~supplied address. The length of the data 
transfer is also set by the user-program. 


NOTE: The Physical Access Method (PAM) provides the user with 
asynchronous waits for I/O operation completions. A 
physical I/0 operation is initiated by a read, rewrite 
or write function request. The data area for the 
physical I/0 operation is defined by UFBRECAREA and the 
data length (UFBBLKSIZE) as returned in the UFB by the 
DMS routine. This data area should not be used until 
the 1/0 operation has been completed successfully; ie., 
it should not be used until a wait for 1/0 completion 
(START(WAIT) function-request) has been executed. 


7.9.1 UFB Field Definitions for Physical Access Method 


1. UFBMAXIFR is a 2-byte positive number which 
indicates the maximum data length which may be 
transferred per I/0 request on a particular disk 
drive. This field is available after OPEN and will 
be a multiple of the disk block size (2048 bytes). 
UFBMAXTFR is 2048 if the device is a printer. 


2. Common PAM Input Parameters 


a. UFBERRAD, UFBLF, jUFBLFMOD and the UFB 
BCBsection are used as in the Common UFB Input 
Parameters. UFBEODAD is taken when File status 
= '23' (record not found) is returned. 


b. UFBKEYAREA - Pointer to word containing the 
beginning block number of the data to be read 
or written. The first block in the file is 
block number zero. 


c. UFBRECAREA - Address (Segment 2) of data. Data 
areas are completely controlled by the 
user-program. The data address must be 
properly aligned; otherwise, file-status = ‘'96' 
will be set for invalid command. (Page 
alignment is required). 


d. UFBBLKSIZE - This 2-byte field indicates the 
length for the data transfer desired. DMS 
function-requests will set UFBBLKSIZE equal to 
the length of the data actually read or written 
when end-of-extent, end-of-cylinder, or 
end-of-file cause the data transfer to be 
truncated. UFBBLKSIZE must be a multiple of 2K 


or file status = '96' will be set for invalid 
command. 
UFBBLKSIZE may equal UFBRECSIZE = 2K for 


appropriate files. In this way, files with 
block size = record size may be accessed 


without record movement and without any extra 
user-program support. In this case, UFBBLKSIZE 


will never be reset by DMS (i.e., the data 
transfered will always = one disk block.) 


7.9.2 Read Block Function-Request (INPUT or I/O) 


Inputs: 


a. Common PAM Input Parameters 


b. UFBEBLK - block number of last block within file 


DMS routine operations: The desired block(s) as indicated by 


Outputs: 


Note: 


UFBKEYAREA and UFBBLKSIZE is read into the user area 
(UFBRECAREA). The read block function is random (block 
number required) and asynchronous. (START is used to 
wait for completion.) File status is set equal '95' if 
there is 1/0 in progress (invalid function sequence). 
File status is set equal to '23' (record not found) if 
the block number supplied is greater than UFBEBLK or if 
the file contains no~ records (UFBEREC=0 and 
UFBEBLK=0). UFBEODAD is taken for file status = '23'. 


UFBFS1, UFBFS2 stored (operation initiated ok or errors 
as above). 

BCB updated for read operation initiated. 

UFBLF set for read. 

UFBBLKSIZE set equal to actual length of the transfer. 


UFBEREC and UFBRECSIZE are available in the UFB and may 
be used by the user-program to determine the last 
record in the last block (end-of-file). (UFBEREC 
equals the number of records in the last block of the 
file; UFBEREC=0 only when the file contains zero 
records (null-file.) 


7.9.3 Rewrite Block Function~Request (1/0) 


Inputs: 


a. Common PAM Input Parameters 


b. UFBEBLK - block number of last block within file. 
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DMS routine operations: The desired block(s) as indicated by 


Output: 


UFBKEYAREA and UFBBLKSIZE is written from the user area 
(UFBRECAREA) to the disk file. The rewrite block 
function-request is random and asynchronous (see ‘Read 
Block", Subsection 4.9.1). The rewrite block 
function-request does not require a prior read_ block 
operation. File status errors ('23' or '95') may occur 
(as in Read block). UFBBUFSIZE is set following the 
initiation of the write operation. (No extents are 
allocated in 1/0 mode.) 


UFBFS1, UFBFS2 stored 

BCB updated for write operation initiated. 

UFBLF set for REWRITE | 

UFBBLKSIZE set equal to the actual length of the 
data transfer 


7.9.4 START Function-Request (INPUT, 1/0, or OUTPUT) 


Inputs: 


a. Common PAM Input Parameters 
b. UFBEBLK ~ block number of last block within file 
c. Modifier byte at UFBVSTART 


DMS routine operations: This function-request has two different 


operations depending on the value of the modifier byte: 


START (WAIT) —- The last I/0 operation is waited on for 
I/O completion. File status = '95' if there is no 1/0 
in progress. The file status of the completed I/O 
operation is available in UFBFS1, UFBFS2 after START 
(WAIT); the record area is also available to the 
user-program after I/O completion. 


The START (WAIT) function-request is required for 
waiting on I/0 completion for all the asynchronous PAM 
operations. 


START OUTPUT/START IO - This request is available only 
in OUTPUT mode and in temporary I/0 mode. It is 
similar to the START request for consecutive disk files 
(Subsection 4.4.4) 


START I0 - The last I/O operation (if any) is waited 
on. Then the vectors are modified to provide the Read 
block and Rewrite block function-requests. The size of 
the file is determined by UFBEBLK. 


START OUTPUT - The last 1/0 operation (if any) is 
Waited on. Then the vectors are modified to provide 
the’ write block function-request. UFBEBLK is set equal 
zero for no records in file. 


START EXTEND ~- This option is similar to START OUTPUT 
except that UFBEBLK is adjusted so that subsequent 
WRITES will add blocks to the end of the file. 
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Outputs (START OUTPUT and START I/O): 


UFBFS1, UFBFS2 stored 
BCB section updated (no I/O in progress) 


For Start I/O- UFBVWRITE set for invalid functions; 
UFBVREAD and UFBVREWRITE set for I/O mode functions. 


For Start Output - UFBVREAD and UFBVREWRITE set for 
invalid function. UFBVWRITE set for OUTPUT mode write 
function. 


UFBFS1, UFBFS2 stored in the UFB; UFBLF and UFBLFMOD 
set. 
BCB section updated for no I/O in progress. 


7.9.5 Write block function-request (OUTPUT) 


Inputs: 


a. Common PAM Input Parameters 
b. UFBEBLK - block number of last block within file 


DMS routine operations: The desired block(s) as indicated by 


Outputs: 


UFBBUFBLOCK and UFBBLKSIZE are written from the _ user 
area (UFBRECAREA) to the disk file. UFBBUFBLOCK is the 
number of the next highest block beyond the current end 
of the file. UFBBUFBLOCK is maintained by DMS and 
allows a file to be created sequentially; it should not 
be modified by the user program. The write block 
function-request is thus sequential and asynchronous. 
The file status for Invalid function ('95') occurs if 
the last write has not been waited on. UFBBLKSIZE is 
set to indicate the length of the data transferred 
after 1/0 initiation. Also, UFBEBLK and UFBBUFBLOCK 
are updated for the number of blocks’ transferred. 
Additional extents are added as necessary; file status 
= '34' when an additional extent is required and none 
can be allocated. 


UFBFS1, UFBFS2 stored 

UFBBLKSIZE set equal to the actual length of the data 
transfer 

UFBBUFBLOCK and UFBEBLK updated for number of blocks 
tansferred. 

BCB section updated (write initiated) 

UFBLF set for write. 


APPENDIX A - DATA AREA MACROINSTRUCTION FORMAT 


Corresponding to each system data structure is a macroinstruction 
which may be used freely by system and user's programs to define 
Standard labels for fields within the structure. If only the 
macroinstruction name is written, a dummy section (DSECT) of that 
name is generated. If a register specification (e.g., UFB 
REG=R1) is included, a USING pseudo-operation is also generated 
(e.g., USING UFB,R1). If the “SUFFIX="" operand is provided, each 
label is generated to contain the SUFFIX character immediately 
following the block name (e.g., for "UFB SUFFIX=#"', the label 
“UFBF1" becomes "UFB#F1"). Only a one-character suffix should be 
specified. If “NODSECT" is specified (e.g., “UFB NODSECT, 
REG=R1") , the DSECT (and termination CSECT) pseudo-operations are 
not generated. The block name is not included as a label name in 


this case. The general format of these macroinstructions is as 
follows: 


MACRO 

blockname &NDS,&REG=,&SUFFIX= 

GBLB &NODS , &blockname 

AIF ('S&SUFFIX' NE'') .LO 

AIF (&blockname) .L3 
&blockname SETB (1) 
LO ANOP 

AIF ('&NDS' EQ 'NODSECT’ OR &NODS).L1 
blockname&SUFFIX DSECT 
-L1 ANOP 
* 
* BLOCK DEFINITION FITS IN HERE 
* 

AIF (‘&NDS' EQ 'NODSECT' OR &NODS) .L2 
&SYSECT &SYSTYP 
.L2 ANOP 

AIF ('&REG' EQ '*).L3 

USING blockname&SUFFIX ,&REG 
Pa ANOP 

MEND 


APPENDIX B - USER PROGRAMS IN THE WANG 2200VS 


THE PROGRAM 


A program is an entity invoked by the command processor or by a 
LINK SVC. The name of the program is the two-level name of its 
disk file. There is only one program in a file. A program file 
is a consecutive file with 1K (1024) byte records and the 
‘program’ flag set in its file descriptor record. The object 
program is originally built by a language translator (compiler or 
assembler). It then may be modified by a linker program. 


THE PROGRAM SKELETON 


A program is partitioned into blocks of information. Each block 
represents common information that will be needed either when the 
program is running or when the program is processed by the linker 
program. To describe the skeleton at this level and for the 
lower levels, a special notation will be used. Each item to be 
described will be listed in a table. To the left of the item's 
description will be its 'level' number and its length. The level 
number is a designation of the relationship of this item with the 
preceding items in the table. The start of the table will be the 
program with a level number of zero. Then to describe structures 
Within the program, there will be one or more level one items 
listed under the level zero item. The first of the items with 
the next higher level number will be assumed to be located at the 
start of the item specified with the lower level number. To help 
see how this system works, take a look at the following example: 


Level Number Length Description 
0 var A 
1 5 B 
2 3 C 
2 2 D 
1 var E 
Example 1 


In this example, the whole is 'A'. The first level below ‘A‘' is 
level 1. There are two parts to this level: ‘B' and '‘E'. The 
start of B corresponds to the start of A. At the next level, 
level number 2, there are also two parts. These are ‘C’ and 
‘D'. The start of C corresponds to the start of B and also the 
start of A. A slightly more general use of this notation would 
specify that there can be any number of replications of B. If 
this was the case: 


Level Length Description 
0 var Object program 
1 var The RUN block 
1 var The SYMBOLIC block 
1 var The LINKAGE block 


THE RUN BLOCK 


This contains the information needed by the system to run a 


program. 


The block will be used by the operating system as a 


paging file when the program is running. It contains the actual 
instructions to be run and the information needed to format the 
‘static’ area on the stack when the program is started. 


Level 


1 


Length 


var 


var 


var 


Description 
The RUN block 


(First location has an assumed address 
of 1,048,576 (or 1024K) .) 


CODE and PROLOG block 
PROLOG block 
Length of CODE and PROLOG block 


(This value is used to find the start 
of the 'STATIC' AND LENGTHS block.) 


Entry point address 


This is the point to which control 
will be passed when the program is 
Started. It will be the address of 
any external name in the CODE 
sections. If the high-order bit is 1, 
the program has been assembled to run 
in segment 0 (as for standalone 
utilities and operating system 
routines). 


CODE block 


This may contain any number of CODE 
sections. This block contains all of 
the executable instructions in the 
program and may contain nonmodified 
data. It is composed of any number of 
sections, where a section is 
contiguous area of code that can be 
moved by the linker program as whole. 
There is no requirement for a 
particular order of the sections 
within the CODE block. 


Level 


4 


Length 


var 


16 


var 


Description 
CODE section 


This is a block externally identified 
by its name. It is an independent 
contiguous area of code supplied by 
the language translator. The first 
location will be on a double word 
boundary, and the length will be 
divisible by eight. All address 
constants that are resolvable will be 
resolved so that the program can be 
run without changing any locations in 
the section. 


LENGTHS block 


Length of ‘static’ block in 


(object time). 


bytes 


This length reflects the length of 
data in the STATIC area. If the 
length is not divisible by 4, up to 
four bytes of slack will be added 
after the end of the block to make the 
following block start on a word 
boundary. These slack bytes are not 
counted in the length. 


Length of ‘static’ area in bytes (run 
time). 


Reserved, must be zero 
Reserved, must be zero 
‘Static’ block 


This block contains sections of 


initial value records. There can be 
any number of 'static' sections in 
this block (including zero). 


"STATIC' BLOCK 


This block contains initial value records that are to be processed 
by the program startup facility in the operating system. These 
records will cause initial values to be assigned to locations in 
the 'static' area. There can be any number of ‘static’ sections 
within this block. All address constants in the static sections 
that reference locations in the CODE sections will be resolved by 
linker or translator programs as if they were in a code section. 
Address constants that address locations within the ‘'static' 
sections will be resolved as if the start of the ‘static’ block 
were location zero. 


Level Length Description 
2 var ‘Static’ block 


This may contain any number of ‘static’ 
sections (including zero). 


3 var "Static' section 


A 'static' section can be any length, 
including zero. The section contains 
only the compressed initial value 
records for this section. If no 
locations in the static section are _ to 
have initial values, there will be no 
records for that section and the object 
time length will be zero. It should be 
noted that the length of these ‘static’ 
sections does not correspond to _ the 
length of the expanded ‘static’ section 
at run time. In order to distinguish 
between the two, the following naming 
convention will be used. Locations in 
the object code (the disk file) will be 
referred to as object time locations or 
will be specified by their object time 
address. Locations that are used 
during running of a program will be 
referred to as run time locations or 
will be specified by their run time 
addresses. Because the CODE block is 
used without change at run time, this 
distinction will normally not be made 
for any locations of the code block. 
When descriptions apply to both static 
and code areas, ‘run time' and ‘object 
time' may be used interchangeably to 
refer to the code area. 


Level 


4 


Length 


5-2054 


Description 
Initial value records 


These records specify locations that 
are to have initial values in the 
named 'static' section and the values 
the program startup mechanism is to 
assign to these locations. There are 
five types of initial value record: 

1) The origin record, which specifies 
how far from the start of the expanded 
run time static area this section will 
start. 

2) The value record which specifies 
the value to be placed into the static 
area. 

3) The relocation record which 
specifies that program startup is to 
supply the address of a run time 
location in a static area. 

4) The repeated record which specifies 
a value and a repetition factor to 
indicate how many occurrences of the 
value are to be placed in the _ static 
area. 

5) The compressed record which 
specifies the compressed value to be 
expanded and placed into the static 
area. 


Length of data within the data field 
in this record minus one (this field 
is not used for the compressed record 
type). 


Record type. 


= 0 Value 

= 1 Origin 

= 2 Relocation 
= 4 Repeated 

= 8 Compressed 


Run time displacement 


This field has two interpretations. 
For origin records (record type - 1), 
this indicates the displacement from 
the start of the static area of this 
static section. For all other record 
types, this indicates the run time 
displacement from the start of the 
static section of the record's data. 
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Data field. The length and format of 
this field varies depending on the 
record type as follows: 


Data field of value type record 


Level 


5 


Length 


1-256 


Description 
Data to be moved to. the ‘static’ 
section. 


This data is moved unchanged to the 
run time static area. 


Data field of origin type record 


Level 


5 


Length 


1 


Description 


One byte of dummy data. 


Data field of the relocation type record 


Level 


5 


Length 


4 


3 


Description 
Relocation item 


These are similar to the relocation 
entries in the linkage block of the 
program. Each’ one represents an 
address constant in the static section 
and the initial value the location is 
to have. Every address constant in a 
STATIC section must be initialized by 
a relocation item. 


Reserved, must be zero 

Base for relocation 

= 0 Relocate relative to the static 
area 

= 1 Relocate relative to the current 


static section 


Length of target address constant 


0 Three bytes 
1 Four bytes 


Direction of relocation 


0 Positive 
1 Negative 
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Do not relocate flag 


QO Relocate the address constant 

1 Move the address constant to the 
specified location but do not 
relocate with respect to the 
Static area. 


This flag is used if the address is 
unresolved, if the address referenced 
a code location, or if this is an R 
type address constant. 


Initial value of the address constant 


If the target is three bytes long, 
only the last three bytes will be 
moved to the target area and _ the 
high-order bit will be ignored. If 
the target is four bytes long, the 
high-order bit will be propagated 
through the seven remaining bits of 
the high-order target byte. 


Data field of repeated type record 


Level 


5 


5 


Length 
2 


1-256 


Description 
Repetition factor (2-32767) 


Data to be repeated wthin the _ static 
area. 


Data field of compressed type record 


Level 


5 


5 


Length 
2 


1-2048 


Description 
Length of compressed data. (1-2048) 
Compressed data 


This data is expanded before being 
moved to the static area. 


THE SYMBOLIC BLOCK 
The symbolic block is a pool of information to be used by _ the 
system's debugging support. The block is partitioned into a 
length field and any number of section related blocks. 

Level Length Description 


1 var The SYMBOLIC block 


This contains all of the program's 
special debugging information. 


2 4 Fullword Aligned Length of SYMBOLIC 
block. 


(If there are no symbolic. sections, 
the length will be 4.) 


2 var Section area 


This can contain any number of 
SYMBOLIC sections. 


3 var SYMBOLIC section 
Every CODE section can have a SYMBOLIC 
section. If it does, these sections 


will be in the same order as_ the 
corresponding CODE sections. 
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THE SYMBOLIC SECTIONS 


The SYMBOLIC section contains information used by the system's 
debugging support for the named code section. It is partitioned 
into a part at the start of the block that contains all of the 
external labels that are referenced, followed by any number of 
subblocks of specialized debugging information. Each of these 
subblocks will contain information grouped by type (i.e., one of 
the blocks may be the 'statement' number block with the list of 
locations of each line of source code's generated object code). 


Level Length Description 
3 var The SYMBOLIC section. 


This is the pool of debugging 
information for the system debugging 
support for the named section. 


4 4 Length in bytes of data in this 
symbolic section (including this word). 


This length reflects the length of 
data in the area. If the length is 
not divisible by 4, up to three bytes 
of x'00' filler will be added after 
the end of the section to make the 
following section start on a_ word 
boundary. These slack bytes are not 
counted in the length. 


4 8 External mame of corresponding CODE 
section. 
4 4 Doubleword aligned object time length 


of the corresponding section block in 
the RUN block. 


4 22 Location of source file at compilation 
time. 

5 8 Source filename. 

5 8 Source Library Name. 

5 6 Source Volume. 


B-10 


Level 


4 


Length 


22 


var 


var 


Description 


Location of listing file at 
compilation time (or blank). 


Listing filename. 
Listing Library name. 
Listing Volume. 

External reference pool. 


This lists all labels that are 
externally referenced. Each label is 
listed only once, no matter how many 
times it is used in the program. 
There is no order in the list, but the 
position of an entry in the list 
represents the internal number’ used 
for referencing that label. This 
Structure allows modules to be added 
or dropped by a linker program without 
changing any locations in SYMBOLIC 
section (other than adding or dropping 
the whole section). 


Length of external reference pool (in 
bytes), including this word. 


Any number of external Reference 
Entries. 


External Reference Entry. 


External name (ASCII with trailing 
blanks). 


Displacement within code section to 
4—-byte RCON. 
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Level 


4 


Length 


var 


var 


var 


Description 
SYMBOLIC subblock area. 


This may contain any number of 
subblocks. Each subblock is composed 
only of one type of debugging 
information (i.e., ‘statement number' 
block). 


SYMBOLIC subblock. 
Subblock type. 


The types are language independent 
codes and are interpreted the same for 
all languages. 


Length of data in subblock. 


This length reflects the length of 
data in the subblock. 


This includes the first four bytes of 
the subblock. 


If this length is not divisible by 4, 
up to 3 bytes of X'00' filler will be 
added at the end of the subblock to 
make the following subblock start on a 
fullword boundary. These filler bytes 
are not counted in the length. 


Collected information about this 
section. These subblocks are 
processed by a common language 


independent program. 
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STATEMENT NUMBER SUBBLOCK 


This subblock is generated by all high-level language 
translators. It contains language independent information 
identifying individual statements in the program's section. 
Exactly one statement number subblock must be present in each 
symbolic section. 


Level Length Description 
5 var STATEMENT NUMBER subblock. 
6 1 = 1 (STATEMENT NUMBER type subblock). 
6 3 Length of data in the  subblock 


including this word. If this length 
is not divisible by 4, up to 3 _ bytes 
of X‘00' filler will be added to the 
end of the subblock to make the 
following subblock start on a fullword 
boundary. 


6 var Any number of statement entries. 


Each entry represents one ‘statement’ 
in the source program. The definition 
of statement is language dependent, 
but is consistent within any one 
language (i.e., in COBOL there will be 
one entry per verb in the COBOL 
source). The entries will be in order 
of increasing displacements. 


7 10° Statement entry. 


8 2 Line number in binary (no negative 
values) or zero to indicate inline 
nonsymbolic code. 


The exact definition of this entry is 
language dependent, but normally will 
indicate the statement line number. 


8 5 Character string (in ASCII with 
trailing blanks), or XL5‘OO' to 
indicate COBOL, perform paragraph 
header linkage. 


The use of this field is language 
dependent, but can be used either for 
the statement label or the command 
starting at the specified 
displacement. (In COBOL this will be 
used for an abbreviation of the COBOL 
verb.) 
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Level 


Length 


Description 


Displacement (run-time) into the code 
SECTION. 


This is the run-time displacement into 


the section of the start of the 
statement. 
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DATANAME SUBBLOCK 


This subblock is generated by all high-level language translators 


to support symbolic access 


to data items at runtime through 


command language facilities. Exactly one dataname subblock must 
be present in each symbolic section. 


Level 


3 


6 


Length 
var 
1 


3 


var 


var 


var 


Description 
DATANAME SUBBLOCK 
=2 (Data name type subblock). 


Length of data in subblock (including 
this word). 


If this length is not divisible by 4, 
up to 3 bytes of X'00' filler will be 
added at the end of the subblock to 
make the next section start on a 
fullword boundary, 


DATANAME INDEX 


This index contains compiler 
dependent information used to 
efficiently search the subblock or a 
given symbol. 


Number of index items. 
Any number of positional index items. 


Index item = displacement within 
symbolic section to first Dataname 
Entry with the compiler dependent 
indexed attribute. 


(For COBOL and BASIC, the index is by 
alphabetical order and points to 
groups of Dataname Entries for 
symbols beginning with the same 
character. This implies that there 
are exactly 26 Dataname Index entries 
for COBOL and BASIC.) 


Any number of data name entries. 


These can be in any order. It is 
expected that any one compiler will 
order these such that when the 
compiler is identified they can be 
efficiently searched. 
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10 


10 


Description 

Data name entry. 

Length of entry minus one. 
Path to the data. 


Index of the external section that 
the displacement references. This is 
the number of the entry in the 
external reference pool in the 
symbolic section. 


Type of path to the data item; 


0= Displacement locates the data 
constant in the corresponding 
code section 


1= Displacement locates the data 
item in the references 
external section. 


2= Displacement locates a 
four-byte ACON in the 
referenced external section 
which should be used as a_ base 
address. The displacement 
from this address is found in 
the offset field. 


3 = Displacement equals value 
(right-justified) 


Displacement from the indexed 
external section to the data item 
(for type 2 path this is the 
displacement to the address constant). 


Data description. 
Type of variable. 
Indicator - referenced item (whether 
referenced using subscripts or not) 


is an elementary data item if = 1. 


Indicator - Subscripts required if = 
1. 


Level 


10 


Length 


6 


Description 


Format Indicator; 


QO0= 


10 


11 


12 


13 


Mixed (applies to 
nonelementary items only 
and implies that the scale 
is to be used as_ the 
high-order byte of the 
variable-length field). 


Character (this implies 
that the scale is to be 
used as part of the 
variable length). 


Binary. 
Packed decimal. 


Bit string (value always 
interpreted as full bytes). 


Floating point. 


Display Field Attribute 
Character 


zoned number with no high 
or low order sign zones 
but may contain either a 
leading or trailing sign 
character and one deciaml 
point character. 


Binary COBOL halfword 
index value (length per 
occurrence number is in 
item length - length is 2 
bytes) . 


Zoned Numeric with 
High-Order Sign Zone. 


Zoned Numeric with 
Low-Order Sign Zone. 


Zoned Numeric with Leading 
Sign Character. 


Zoned Numeric with 
Trailing Sign Character 


Level 


Length 


Description 
Format Indicator: 
14 = Unsigned Zone Numeric 


Note: Zoned numeric fields 
contain all numeric. characters, 
0-9, except for sign. Scale 
factor indicates decimal point 
location. 


15 = BASIC array. 

16 = COBOL group item. 

17 = BASIC string scalar. 

18 = Binary COBOL fullword 
index value (Length per 
occurrence number is in 
item length. Length is 
two bytes). 

19 = Logical (FORTRAN) 

20 = Complex (FORTRAN) 

Scale 


This is a signed binary number 
indicating how far left of the 
rightmost digit the decimal point 
is to be relocated (relocation is 
to the rigth fro negative 
numbers) . (For character type 1 
fields, this byte will be 
considered part of the item 
length.) 


Data item length. 


This specified the length of the 
data time. If the data is 
character type, both this and_ the 
preceding byte will be used for 
the length. 


Length of data name minus one. 
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Level 


10 


11 


11 


* For the 


Length 


var 


var 


var 


Description 


Data name. 


If the data name must be 
qualified, all necessary levels of 
the name are to be listed with 
highest level first and the 
levels of qualifications separated 
by points ('.'). If the name is 
qualified but is unique in the 
program, only the lowest level of 
the name should be listed. 


Optional offset (present with data 
path 2 only). 


Array descriptor. 
Number of subscripts required. 


There will be one dimension 
description for each subscript. 


Indicated number of dimension 
descriptions. 


Dimension description. 


There will be one entry for each 
subscript indicated in the maximum 
subscript value (entry for leftmost 
subscript first). The first element 
of each dimension of the array will be 
assumed to be l. 


High bound of subscript 


Length of Subscript Item.* 


general array: A[1.. uz, les sting eee, 1e+ ty], the 


"Length of Subscript Item" for the jth subscript (LSI 5) is 
defined as follows: 


For Row Major Ordering, 


LSI 


i] 
=) 
c= 


j 1 =J =n- 
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1 


For Column Major Ordering, LSI; = j-1 
ai0 U, 2 =j =n 
k=1 


The Length of Subscript Item entry is used by internal routines of the 
Symbolic Debugger to efficiently locate array elements in a storage 
independent manner.e The following formula is used to locate element 
Al ijsipe ses eee ,in |? 


n 
LOC A[iz,in--+++++,ip] = LOC A[11...-.1,] + ))  LSI5* (45-1) 


j=l 


THE LINKAGE BLOCK 


This is a pool of information required for the linker program to 
add or delete sections of the program. It is partitioned into a 
length field and then any number blocks of section information. 


Level 


1 


2 


Length 


var 


4 


var 


var 


var 


var 


Description 
The LINKAGE block. 


Fullword aligned length of the LINKAGE 
block. 


CODE section block area. 


This is composed of exactly one 
section block for each CODE section. 
The blocks are in the order in which 
the CODE sections appear in the CODE 
block of the RUN block. 


CODE section block. 

‘Static’ section block area. 

This is composed of exactly one 
section block for each *static’ 
section. The blocks are in the order 
in which the ‘static’ sections appear 


in the 'STATIC' block. 


‘STATIC’ section block. 
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CODE AND 'STATIC' SECTION BLOCKS IN THE LINKAGE AREA 


These blocks have sufficient information so that sections can be 
added to or deleted from a program, and so that all addresses can 
be correctly resolved after this operation is complete. With 
minor exceptions both the CODE and the STATIC blocks have the 
same basic skeleton. One skeleton will be presented, and _ the 
differences will be noted in the skeleton. 


Level Length Description 
3 var Section block (CODE or STATIC). 
4 4 


Length of data in this section block in bytes. 


This length reflects the length of data in the area. If the 
length is not divisible by 4, up to three bytes of X'00' filler 
will be added after the end of the block to make the following 
block start on a word boundary. These filler bytes are not 
counted in the length. 


4 8 
External name of section (in ASCII with trailing blanks). 


4 1 Type of block: 
= 0 for code and = 1 for static. 
4 3 


Doubleword aligned object time length of the corresponding 
section block in the RUN block. 


4 4 
Compiler name or designation (ASCII with trailing blanks). 


4 1 
Version and modification level of the compiler (packed decimal) 


VM. 


4 3 
Date of compilation of this section (packed decimal) YYDDD. 
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Level 


4 


Length 


4 


var 


var 


var 


Description 


For a CODE section block: 
Fullword aligned length of the 
corresponding SYMBOLIC section 
(or =0 if there is no 
corresponding SYMBOLIC section). 
For a STATIC section block: 


Doubleword aligned run time 
length of section block in the 
RUN block. 


ENTRY POINT list. 


(This is a list of all names in this 
section that are known outside of the 
section.) This list may have any 
number of names. 


Length of ENTRY POINT list (including 
this word). 


The list. 


This may contain any number of names 
and address pairs. They may be in any 
order, but must not be repeated. 


ENTRY POINT name (ASCII with trailing 
blanks) . 


Runtime displacement into the section 
of this ENTRY POINT. 


RELOCATION REFERENCE BLOCK. 


This lists all locations within the 
section that will need to have 
addresses changed if the relative 
location of the section within the 
program is changed or if the location 
of specified external labels changes. 


RELOCATION REFERENCE BLOCK 


All address constants in the section that would be relocated if 
either the starting location of the section or the location of an 
external name was changed will be listed in this block. The 
block is composed of two main parts: a list of external names 
and a list of addresses in the section to be relocated. 


Level Length Description 
4 var RELOCATION REFERENCE BLOCK. 


This block contains all of the 
information required to relocate 
address constants in this section. 


5 4 Actual length in bytes of the 
RELOCATION REFERENCE BLOCK. 


This includes this word, the EXTERNAL 
NAMES BLOCK, and the relocation 
items. 


a var EXTERNAL NAMES BLOCK. 


This block contains a list of all 
external names referenced by this 
section. An external reference is an 
address constant that references a 
label that is not part of the current 
section. The label must be the name 
of a section or an ENTRY type symbol 
in a section. 


6 4 Length of # external names block 
(including this word). 


6 var List of external reference names. 


These names can be in any order, but 
they will be referenced by their 
position in the list. The first name 
is number one. 


7 8 External name (ASCII with trailing 
blanks). 
5 var List of relocation items. 


This list is in order of increasing 
displacements. There can be any 
number of entries in this list. 


Level 


Length 
5 
1 


i2 


Description 

Relocation item. 

Flag byte. 

Reserved, must be zero. 
RCON if = 1. 


The referenced name must be in a 
STATIC section. If the address 
constant is in a STATIC section, the 
relocation record will have the do not 
relocate bit set. 


Address is a relocation record (8 
bytes). (If this is set, the 
following bit of length of target is 
ignored.) All items in a ‘STATIC’ 
section except origin records and none 
in a CODE section will have this bit 
set. 


Length of target address constant: 


Q Three bytes. 
1 Four bytes. 


Direction of relocation: 


= 0 Positive (add the address of the 
start of the section to the 
specified location. 


= 1 Negative (subtract from the 
location). 


Unresolved flag if set to =1 (if set, 
the address will be resolved relative 
to an address of X'FO0000'). 


Reserved, must be zero. 


Object time displacement into the 
section of the address constant. 


Number of external name referenced. 


This number is either zero if the item 
is to be relocated relative to the 
start of this section or is the number 
of the external name in the EXTERNAL 
NAMES BLOCK (the first name in the 
list is one). 


B-25 


TRANSLATOR PROCESSING 


The object program is produced by a language translator. At this 
time, all address constants will be resolved, or marked as 
unresolved. The program can then optionally be processed by the 
linker program. It will add, rearrange or delete sections in the 
program. After either a language translator has produced an 
object program or a linker program has processed it, the program 
can be invoked by the operating system. 


The language translator creates a complete object program that is 
runnable by the operating system (if no sections are unresolved 
at translation time). This program must have linkage information 
for the linker program to resolve addresses after adding or 
deleting sections. The translator also has the responsibility to 
generate the symbolic section of information for debugging. 


1. The RUN block - This contains all of the information 
required to run the program. The operating system will 
use this part of the file for segment one of the 
running program. This area contains the code sections 
and the initial value records used to initialize the 
static areas when the program is started. 


2. The SYMBOLIC block - This contains information to aid 
in run time debugging of the program. This area is 
used by the debug facilities in the HELP processor. 


3. The LINKAGE block - This information is used by the 
linker program. After adding or deleting sections, the 
linker program will relocate the address constants in 
the program using this information. 
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LINKER PROCESSING 


When the 


perform 
program: 


ae 


linker program processes an object program, it will 
the following operations to the basic parts of the object 


The RUN block ~ It can add new sections to either the 
code or the static areas. These must be added as a 
whole section. It can also delete whole sections or 
reorder the sections, again only as whole sections, 
never as a part of a section. Locations within the 
sections will not be inspected or changed other than 
relocatable address constants having their values 
adjusted by the linker. In some circumstances, the 
linker may have to change a flag in one of the 
relocation records. When a section is deleted from a 
program, all relocation records that reference that 
section must have the flag turned off. If a static 
section is added, all references to it must be 
examined. If the reference is in a code section, it 
must be an R type (relocation address constant) of 
address constant. If not, it will be flagged as an 
error. 


Only the terms add or delete have been used. Although 
the linker can be used to replace a section, this 
should be considered a deletion of the current section 
and an addition of the new section. 


The LINKAGE block - When a code or static section is 
added or deleted, the linker will add or delete the 
corresponding linkage section. It will also adjust the 
object time and run time starting address of the 
sections that follow. When adding a section, all 
references to it are marked as resolved and _ relocated. 
If a section is deleted, all references are marked as 
unresolved and are relocated relative to hexadecimal 
FOO000. 


The SYMBOLIC block - If a section is added or deleted, 
the linker will add or delete the corresponding 
symbolic section. It will not inspect or change any of 
the records within a section for any reason. 
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RUN_ PROCESSING 


A program is invoked by the command processor or by another 
program using the LINK facility of the operating system. First, 
the run portion of the program is made addressable as segment 1. 
(The first location will be location 1,048,576.) The system will 
then double word align the stack, find out the run time length of 
the static area and push this much space onto the stack. The 
start of this area will be passed to the program in register 14. 
The initial value records will then be processed. When an origin 
record is encountered, the origin displacement will be added to 
the value in register 14 and this will be used as the starting 
location of the section. When either text or relocation records 
are read, their displacement will be added to this value and 
moved to the location calculated. If a relocation record has the 
relocate flag on, the value in register 14 is to be added to the 
initial value in the record. 
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APPENDIX C DATA MANAGEMENT SYSTEM MESSAGES 


Appendix C contains the following types of messages, listed in 
the order they appear in the appendix: 


- SVC OPEN Cancel Messages. 

. SVC OPEN Respecify Messages. 

DMS Function-Request Cancel Messages. 

- SVC CLOSE Cancel Messages. 

. File Status (FS) Codes for DMS and ADMS. 


wm PWh ee 


The following types of messages are not included in this appendix: 


1. Messages issued by program 'BUILDALT' for OUTPUT mode 
creation of alternate indexed files (acknowledge and 
cancel messages). 

2. Miscellaneous acknowledge messages from SVC OPEN and 
DMS function requests. 


VS DMS No-Message Option 


The No-Message Option is available in SVC OPEN, SVC CLOSE, and 
DMS. This option causes the suppression of messages normally 
appearing on the workstation screen. 


If UFBF4NOMSG = 1, the file status for the operation is set equal 
to C'60'. For SVC OPEN and SVC CLOSE, the message ID is stored 
in the first four bytes of the UFB. Return is made using the 
address in UFBERRAD; if this address is zero, UFBF4NOMSG is 
ignored. 


1. SVC OPEN Cancel Messages 


These messages deal primarily with invalid information supplied in the 
UFB. Some also refer to unusual conditions that rarely arise during normal 
SVC OPEN usage; for example, UPDATFDR SVC errors, I/O errors when reading AXD1 
blocks, etc. 


NOTE 


There is no continuation possible when these messages are issued. 


ERROR 

NUMBER MESSAGE 
INVALID UFB ADDRESS PRESENTED TO SVCOPEN. 

E001 DEVICE CLASS (XX) = INVALID OPEN MODE (XX) = INVALID FIL 
ORGANIZATION (XX)= INVALID RECORD SIZE = INVALID RECORDS ARE FIXED 
LENGTH. KEY SIZE = XXX KEY POSITION = INVALID 
| E006 — | TASK WORKSTATION NOT AVAILABLE. 


E007 | MAXIMUM NUMBER OF FILES ALREADY OPEN 


EQ11 REQUIRED BUFFER(S) NOT AVAILABLE FOR FILE PROCESSING 
E014 UNEXPECTED DEALLOCATION ERROR FOR MAGTAPE DEVICE. 


BACKGROUND TASK ATTEMPTED TO OPEN WORKSTATION. THE WORKSTATION MAY 

BE OPENED IN FOREGROUND ONLY. i 

INVALID OPEN MODE FOR PHYSICAL ACCESS METHOD. (EXTEND AND SHARED 
MODES ARE INVALID.) 

THE PROGRAM IS REQUESTING AN INVALID OPEN MODE (SHARED, EXTEND) FOR 
A FILE RESIDING ON AN UNSTRUCTURED DISKETTE VOLUME. 


E019 THE PROGRAM IS REQUESTING AN INVALID MODE (EXTEND MODE) FOR INDEXED 
FILE PROCESSING. 


THE PROGRAM IS REQUESTING AN INVALID FILE ORGANIZATION (INDEXED) 
FOR A FILE RESIDING ON AN UNSTRUCTURED DISK VOLUME. 

INVALID ACCESS METHOD SPECIFICATION IN UFB (UFBF1). 

BLOCK ALLOCATION ERROR. SPACE NOT AVAILABLE ON VOLUME AND 
EXIT-OPTION NOT IN USE. 


E025 THE PROGRAM IS REQUESTING AN INVALID MODE (SHARED MODE) FOR FILE 
PROCESSING UNDER THE BLOCK ACCESS METHOD (BAM). 


SHARING TASK NOT ACTIVE. 

UNABLE TO GET UNIQUE PORT NAME. 

SHARER RESPONSE CODE = XX-YYYY. UNEXPECTED ERROR HAS OCCURRED 
WHILE OPENING A FILE FOR SHARED ACCESS. 

E030 INVALID BUFFER POOL SPECIFICATION. (ACCESS METHOD SUPPLIED I 
INVALID.) BUFFER POOLING CAN ONLY BE USED WITH INDEXED FILES IN 
INPUT OR IO MODE. 

E031 

E032 THE BUFFER POOL TABLE HAS NOT BEEN CORRECTLY INITIALIZED. 

THE BUFFER COUNT SUPPLIED BY THE PROGRAM IS TOO SMALL. THE MINIMUM 
BUFFER COUNT IS 3. 

E034 AN UNEXPECTED ERROR HAS OCCURRED WHIE UPDATING THE FILE LABEL. THE 
FILE CANNOT BE SUCCESSFULLY OPENED FOR UPDATE. 

THE ALTERNATE INDEX BLOCK (AXD1) ADDRESS SUPPLIED IS INVALID. 


ERROR 
NUMBER MESSAGE 
ALTERNATE INDEX INFORMATION FOR FILE CREATION IS INCORRECT. 
UNABLE TO SET UP THE MAPPING CONTROL TABLE (MCC) FOR THE ADMS FILE 
IN SHARED MODE. 
E056 
ADMS FILE IS INVALID. 
UNABLE TO EXTRACT INFORMATION FROM DATA DICTIONARY TO SET UP THE 
THE PROGRAM HAS ATTEMPTED TO PROCESS AN ADMS FILE, BUT THE VIEW OF 
THE FILE IS NOT OPENED. 


THE ADDRESS OR SIZE OF THE MAPPING CONTROL TABLE (MCC) FOR THIS 
E057 
UFB FOR THIS ADMS FILE. 


THE VIEW OF THIS FILE DOES NOT HAVE THE EXLCUSIVE ACCESS RIGHT TO 
OPEN IT IN NON-SHARED MODE. 


ee | THE PROGRAM HAS ATTEMPTED TO OPEN AN ADMS FILE, BUT THE FILE 
| E061 


SPECIFIED IS NOT AN ADMS FILE. 
E061 ADMS DATA DICTIONARY ERROR--INCORRECT FILE ATTRIBUTE FOUND. 
THE PROGRAM HAS ATTEMPTED TO OPEN AN EXISTING ADMS FILE IN A 
DATABASE WITH RECOVERY. BUT THE DATABASE HAS NOT BEEN BACKED UP, 
AND RECOVERY CANNOT WORK WITHOUT THE BACKUP. PLEASE RUN DATABASE 


al BACKUP. 


E063 THE PROGRAM HAS ATTEMPTED TO CREATE AN ADMS FILE IN A DATABASE WITH 


RECOVERY BUT OUTPUT MODE WITH RECOVERY IS NOT ALLOWED AFTER SCHEMA 
BACKUP. THE SCHEMA MUST BE RE-ACTIVATED W/O RECOVERY. 


E064 ADMS FILE CREATION ERROR--UNABLE TO RECORD THE CREATION OF THIS 
FILE IN THE DATA DICTIONARY. 
E065 THE ADMS FILE TO BE OPENED IS NOT YET LOADED INTO THE DATABASE. 


UNABLE TO COMMUNICATE WITH SHARER TASK TO OBTAIN SCHEMA STATUS. 
E083* THIS FILE IS PART OF AN ADMS DATABASE WHICH HAS ENCOUNTERED A CRASH 


CONDITION. RESTORE MUST BE RUN BEFORE THE FILE CAN BE SUCCESSFULLY 
OPENED IN ADMS MODE. 


* This is a new error message added to OS Release 5.1. Older OS releases do 
not generate this error. 
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2. SVC _ OPEN Respecify Messages 


These messages deal with situations where the user may successfully 
continue either by supplying additional information or by correcting 
information already supplied. Situations involving possession conflicts or 
volume mounting are also handled by these respecification messages. The user 
may always continue after a respecify message. 


ERROR 

NUMBER _ MESSAGE 

FILE IDENTIFICATION INFORMATION IS INCOMPLETE. PLEASE SUPPLY THE 
MISSING INFORMATION BELOW 


BE CREATED. THIS VALUE WILL BE USED FOR INITIAL DISK-SPACE 
ALLOCATION. __ 

DEVICE SPECIFIED IS UNKNOWN OR NOT SUPPORTED. PLEASE RESPECIFY. 

DEVICE SPECIFIED IS INVALID FOR THIS PROCESSING MODE. PLEASE 
RESPECIFY. 

THE PROGRAM IS NOT REQUESTING A CONSECUTIVE-PRINT FILE. THEREFORE, 


ROO2 PLEASE SUPPLY THE APPROXIMATE NUMBER OF RECORDS IN THE DISK FILE TO 


THE FILE CANNOT BE ASSIGNED TO A PRINTER. PLEASE SPECIFY ANOTHER 
DEVICE TYPE. ; 

DEVICE NUMBER INCORRECTLY SPECIFIED. PLEASE RESPECIFY DEVICE (E.G. 
PRINTER 3). (NOTE--DEVICE NUMBER IS OPTIONAL AND MAY BE OMITTED). 


DEVICE NUMBER DOES NOT CORRESPOND TO DEVICE CLASS. PLEASE 
RESPECIFY DEVICE. Seeks 
NO PRINTER CURRENTLY AVAILABLE. ASSIGN OUTPUT TO DISK OR FREE 
PRINTER FOR ALLOCATION. 


R013 THE FILE BELOW IS ALREADY OPENED BY THIS PROGRAM. PLEASE SPECIFY 
ANOTHER FILE. 


RO14 LIBRARY NOT FOUND IN VOLUME TABLE OF CONTENTS. PLEASE RESPECIFY 
LIBRARY. 


RO16 THE FILE SPECIFIED IS IN USE AS A SYSTEM-ONLY PAGING FILE. PLEASE 


RESPECIFY. 
RO18 


THIS FILE IS CURRENTLY IN USE AS A PROGRAM FILE. THEREFORE, 
ONLY BE OPENED IN INPUT MODE. PLEASE RESPECIFY THE FILE. 

UNEXPECTED CREATFDR SVC ERROR. 

FILE SPECIFIED ALREADY EXISTS. PLEASE RESPECIFY FILE. 

VTOC FULL, NO ROOM FOR FILE LABEL. PLEASE SPECIFY ANOTHER VOLUME. 


IT CAN 


RO20 VOLUME FULL, NO ROOM FOR FILE. PLEASE SPECIFY ANOTHER VOLUME OR 
USE A SMALLER FILE SIZE. 
RO21 INVALID INFORMATION IN FILE LABEL. PLEASE RESPECIFY FILE. 


THE FILE AT POSITION XXX WITHIN THE TAPE VOLUME IS XXXXXXXXXXXXXKX. 
THIS DOES NOT AGREE WITH THE FILE SPECIFIED BELOW. PLEASE 


RO22 THE TAPE SPECIFIED BELOW IS AN NL-TAPE, BUT PROGRAM REQUIRES A TAPE 
WITH A DIFFERENT LABEL TYPE. PLEASE RESPECIFY. 
RO24 


RESPECIFY. __ 
THE DEVICE SPECIFIED IS ALREADY IN USE BY THIS PROGRAM. PLEASE 
RESPECIFY. 
THE DEVICE SPECIFIED HAS BEEN LOGICALLY DETACHED AND IS THEREFORE 
NOT AVAILABLE. PLEASE RESPECIFY. 
THE ao REQUIRES XXXXXXXXXK. THE FILE SPECIFIED BELOW IS XXXXX 
PLEASE RESPECIFY. 


ERROR 
NUMBER _ MESSAGE 


RO28 THE PROGRAM REQUIRES A FILE CONTAINING XXXXX-CHARACTER RECORDS. 
THE FILE SPECIFIED BELOW CONTAINS XXXXX-CHARACTER RECORDS. PLEASE 
RESPECIFY. 

A FILE SEQUENCE NUMBER OF ZERO IS INVALID. PLEASE RESPECIFY. 

RO30 TAPE IO ERROR OCCURRED DURING TAPE POSITIONING OR LABE 
PROCESSING. IOSW = XXXXXXXK XXXKXXXXX. PLEASE RE-MOUNT THE TAPE 
VOLUME IN ORDER TO TRY AGAIN. 


PROCESSED IN OUTPUT OR EXTEND MODE. PLEASE PUT A WRITE-ENABLE RING 
ON THE TAPE, AND RE~MOUNT THE VOLUME, OR USE (ENTER) TO RESPECIFY. 

THE UNSTRUCTURED DISKETTE VOLUME SPECIFIED FOR OUTPUT IS CURRENTLY 
IN USE. PLEASE RESPECIFY. 

THE PROGRAM IS REQUESTING A FILE THAT RESIDES ON AN UNSTRUCTURED 


RO31 THE TAPE VOLUME IS WRITE-PROTECTED, AND ‘THEREFORE CANNOT B 


DISK VOLUME. THE FILE SPECIFIED BELOW RESIDES ON A DISK VOLUME 
WITH A VTOC. PLEASE RESPECIFY. 

THE INDEXED FILE SPECIFIED BELOW CAN NOT BE PROCESSED IN EXTEND 
MODE. PLEASE RESPECIFY. (EXTEND MODE IS ONLY SUPPORTED FOR 
CONSECUTIVE FILES.) re 

THE INDEXED FILE SPECIFIED BELOW WAS NOT CLOSED AT FILE CREATION. 


THE FILE IS CURRENTLY NOT USEABLE AND SHOULD BE RE-CREATED. PLEASE 
SPECIFY ANOTHER FILE. 


R036 THE FILE SPECIFIED BELOW WAS NOT CLOSED AT FILE CREATION. 
THEREFORE, THE FILE LABEL INDICATES THAT THE FILE CONTAINS NC 


RECORDS. IF YOU WISH TO ACCESS THE WHOLE FILE SPACE (MAXIMUM 
NUMBER OF RECORDS), USE PF2 AND THE END-OF-FILE INDICATOR WILL BE 
SET ACCORDINGLY. OTHERWISE, PLEASE SPECIFY ANOTHER FILE. Peet 

CODE = XX; UNEXPECTED OUTPUT-FILE SCRATCH ERROR. PLEASE SPECIFY 
ANOTHER OUTPUT FILE NAME IN ORDER TO CONTINUE. 

R038 UNABLE TO FIND FILE SPACE ON ANY ELIGIBLE VOLUME. PLEASE SPECIFY A 
SMALLER FILE, USE A PRIVATE VOLUME, OR RELEASE (THROUGH SCRATCH) 
THE REQUIRED DISK SPACE. 

THE DISKETTE VOLUME SPECIFIED BELOW IS WRITE-PROTECTED. PLEASE 
RE-MOUNT THIS DISKETTE WITH WRITE-ENABLED, OR SPECIFY ANOTHER FILE. 

RO4O THE FILE SPECIFIED BELOW ALREADY EXISTS. USE PF3 IF YOU WISH Td 
SCRATCH THE EXISTING FILE AND CONTINUE. OTHERWISE, PLEASE SPECIFY 
ANOTHER FILE NAME. 


THE FILE SPECIFIED BELOW IS CURRENTLY IN USE AND CANNOT BE 
SCRATCHED, PLEASE SPECIFY ANOTHER OUTPUT. FILE NAME. 

RO45 ENTER KEY USED WITH INVALID DEVICE SPECIFICATION BELOW. USE PF 

es KEY FOR MOUNT OPERATION. IF A MOUNT OPERATION IS NOT REQUIRED, 
PLEASE USE THE ENTER KEY WITH DEVICE = DISK. 


INVALID VALUE ENTERED FOR PRINTER OPTION. FORM # MUST BE LESS 
256. PRICLASS MUST BE A LETTER (A-Z). COPIES MUST BE A NUMBER 
BETWEEN 1 AND 32,767. PLEASE RESPECIFY. 


RO49 THE FILE SPECIFIED BELOW IS A PROGRAM FILE WITH SPECIAL ACCES 
RIGHTS. ONLY A SECURITY ADMINISTRATOR MAY MODIFY THIS FILE. 
PLEASE RESPECIFY. 

R049 THE CURRENT USER DOES NOT HAVE THE REQUIRED ACCESS RIGHTS FOR THE 


FILE SPECIFIED BELOW. PLEASE RESPECIFY. 


R047 SHARER RESPONSE CODE = XX-YYYY. CONSULT SHARER ERROR LIST FOR 
EXPLANATION. PLEASE SPECIFY ANOTHER FILE IN ORDER TO CONTINUE. 
R048 
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ERROR 
NUMBER _ MESSAGE 


RO50* THIS FILE IS A PARTIAL FILE CREATED BY BACKUP, AND MAY BE OPENED IN 
BAM OR PAM, WITH THE PARTIAL FILE FLAG SET. PLEASE RESPECIFY. 


THE SHARER HAS RUN OUT OF MEMORY FOR ITS CONTROL BLOCKS. THIS FILE 


MAY BE OPENED SUCCESSFULLY AFTER ENOUGH MEMORY HAS BEEN RELEASED 
(BY OTHER SHARED USERS). 

THE FILE BELOW IS ALREADY OPENED IN SHARED MODE BY THIS PROGRAM. 
PLEASE SPECIFY ANOTHER FILE. 

FILE SPECIFIED NOT FOUND IN LIBRARY. PLEASE RESPECIFY FILENAME. 

LIBRARY NOT FOUND IN VOLUME TABLE OF CONTENTS. PLEASE RESPECIFY 


LIBRARY. 

R059 THE VOLUME SPECIFIED IS MOUNTED FOR EXCLUSIVE USE. A FILE ON & 
EXCLUSIVE VOLUME MAY NOT BE SHARED. PLEASE SPECIFY ANOTHER FILE 
(OR RE~MOUNT THIS VOLUME). 


PLEASE MOUNT THE DISK 


RO60 THE PROGRAM REQUIRES A FILE WITH A DIFFERENT FILE-ORGANIZATION FROM 
THE FILE SPECIFIED BELOW. PLEASE RESPECIFY. 
FILE SPECIFIED BELOW. PLEASE RESPECIFY. 

eee THE DISK VOLUME SPECIFIED IS NOT MOUNTED. 

R063 THE FILE SPECIFIED BELOW IS CURRENTLY IN NON-SHARED USE. PLEASE 
RESOLVE THIS POSSESSION CONFLICT OR RESPECIFY. 
SCRATCH THE FILE SPECIFIED BELOW. PLEASE SPECIFY ANOTHER FILE. 

RO65 THE RETENTION PERIOD FOR THE FILE SPECIFIED BELOW HAS NOT EXPIRED. 
MODIFIED. PLEASE SPECIFY ANOTHER FILE OR USE THE COMMAND PROCESSOR 
TO MODIFY THE EXPIRATION DATE AND SCRATCH THIS FILE. 

RO66 THE CONSECUTIVE FILE SPECIFIED BELOW CAN NOT BE OPENED IN SHARED 
MODE. PLEASE RESPECIFY. 
NOT BE "#'', PLEASE RESPECIFY 

RO68 THE PROGRAM WILL NOT ACCEPT THIS FILE FROM TAPE. PLEASE RESPECIFY. 


THE PROGRAM REQUIRES A FILE WITH A DIFFERENT RECORD SIZE FROM THE 
VOLUME OR RESPECIFY. 
THE CURRENT USER DOES NOT HAVE THE REQUIRED ACCESS RIGHTS TO 
THE FILE CANNOT BE SCRATCHED UNLESS THE EXPIRATION DATE IS 
THE FIRST CHARACTER OF A LOG-FILE BEING OPENED IN SHARED MODE MAY 


VOLUME FULL, UNABLE TO ADD ANOTHER FILE ON THE TAPE. PLEASE 
RESPECIFY. 

THE TAPE FILE SPECIFIED BELOW IS NOT ON THE TAPE VOLUME. PLEASE 
RESPECIFY. 


THE DEVICE SPECIFIED IS NOT A TELECOMMUNICATION DEVICE. 

RESPECIFY. 

CONTROL BLOCKS (PPB, LCB) FOR THIS TC DEVICE ARE NOT PROPERLY SET 
UP. PLEASE RESPECIFY. 

UNABLE TO CONNECT THE TC LINE, OR INCORRECT CONNECT PARAMETERS 
SUPPLIED. PLEASE RESPECIFY. 

THE PROGRAM HAS SUPPLIED AN INVALID ADDRESS FOR THE CONNECT 
PARAMETER. PLEASE RESPECIFY. 

THE TAPE VOLUME IS NOT THE CORRECT SEQUENTIAL VOLUME FOR THIS TAPE 

RO78 


PLEASE 


FILE. PLEASE RESPECIFY. 
EXTEND MODE PROCESSING FOR IBM LABELED TAPE IS NOT SUPPORTED. 
PLEASE RESPECIFY. 


ERROR 

NUMBER MESSAGE | 

THE PROGRAM HAS ATTEMPTED TO OPEN A RE-RESTART FILE, BUT THE FILE 
SPECIFIED IS NOT A RESTART FILE. PLEASE RESPECIFY. 

R081 


ATTRIBUTES. BUT THESE ATTRIBUTES ARE ASSIGNED BY 
DICTIONARY AND CANNOT BE CHANGED AT OPEN. THEIR CORRECT VALUES 
ARE DISPLAYED BELOW, PRESS (ENTER) TO CONTINUE. 


* With the introduction of OS Release 5.1, the text for error number RO50 is 
modified as follows: 


THIS FILE IS A PARTIAL FILE CREATED BY BACKUP FOR USE BY RESTORE. IT MAY 
BE OPENED ONLY IN BAM OR PAM, WITH THE PARTIAL FILE FLAG SET. PLEASE 
RESPECIFY. 
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3. DMS Function-Request Cancel Messages 


The file status message (ID = 000) covers all file status values including cases where the 
significance of the. FS value is determined by additional factors such as current function request and file 
organization. The file status message appears as a cancel message if UFBERRAD = 0. Otherwise, an 


acknowledge message is issued before taking the error exit. (The acknowledge message may be masked out by 
using UFB4NOACK. ) 


Other DMS cancel messages reflect unusual conditions caused mainly by incorrect user modification of 
UFB fields, unexpected errors, or invalid block contents for indexed file processing. 


These messages may be issued as a result of any one of the five DMS function requests or by the DMS 
CLOSE vector (for the last I0 operation on the file). 


ERROR 
NUMBER MESSAGE POSSIBLE CAUSE 


. FILE STATUS error message. Refer to page 354.3. 
eee rene 
UFBBCBFLAGS). 


INVALID BLOCK NUMBER DETECTED 8Y SVC XIO UFBBUFBLOCK contains invalid data. Can be 
(UFBBUFBLOCK) WHEN ATTEMPTING DISK I/O. caused ve invalid data in Data Link Chain of the 


fall 1 anadiemaie aes eeichckientsnihianasbdsam 
UFBRECSIZE=0 

BEGINNING OF FUNCTION REQUEST. 

ball Riorislelacanelescabansn ICA 5 hntoleaennbaaconsied 
is not an OFB. 

ALLOCATE AODITIONAL DISK SPACE. cation of a serious DMS problem. 

vTOC 1/0 ERROR OCCURED DURING SVC ALEX. A vToOC 10 error occurred while trying to obtain 
an additional extent. ALEX is an acronym for 


Allocate Extent. : 
UNABLE TO ALLOCATE DISK EXTENT SINCE ALL ALEX return code = 20. No work space available 
BUFFERS OR GETMEM POOL _IN USE. for UPDATFOR. : 
ee MAG TAPE READ OPERATION FAILED; NO DATA WAS Residual count greater than or equal to block 
TRANSFERRED. Size--probable IOP firmware error. 
pies FUNCTION-REQUEST ISSUED ON NON-OPENED FILE. Before performing a task within a file, the file 
oe] SECOND PHYSICAL I/O OPERATION ISSUED ON FILE 
WITHOUT WAITING FOR PREVIOUS I/O COMPLETION. 
ERROR FOUND WHILE READING FILE INDEX. THIS 


FILE SHOULD BE REORGANIZED IN ORDER TO GENERATE 
THE INOEX CORRECTLY. 


Occurs when two XIO's in a row were performed 
with no CHECK operation between them. 


Invalid condition exists in the index block 
currently being read. 
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INVALID BLOCK NUMBER FOUND WHILE BUILDING OR Occurs when contents of a Data Link Chain in a 
UPDATING THE FILE INDEX. data block contains incorrect data. This error 
FILE INDEX. qenerated when data length in block exceeds 7FC. 


block length, the difference must equal zero. 
This error occurs when it is not 


INVALID UFB FIELD FOUND FOR REWRITE OPERATION User damaged segment 2 (UFB) data. 
OFFSET=0). 


BUFFER POOL ERROR DETECTED. LOCKED BUFFER User damaged segment 2 (UFB or BCT) data. 
(BCE) IN CONTROL TABLE DOES NOT AGREE WITH 
CURRENT BUFFER (BCB). 


WITH CURRENT READ REQUEST. invalid, 
BUFFER POOL ERROR DETECTED. BLOCK TYPE (BCE) 
IS INVALID FOR IO INITIATION. 


BUFFER POOL ERROR DETECTED. BUFFER (BCE) WITH User damaged UFB or BCT. 
IO IN PROGRESS NOT ON BCTBL CHAIN OR INTERNAL 
LOCK OTHER BCE OPERATION FAILED. 


Alternate index block contains a primary key 
STRUCTURE, UNABLE TO LOCATE THE RECORD value which is not in any data block. 
ALTERNATE TREE NOT MOOIFIED. invalid for a user. 


UNEXPECTED ERROR OCCURED DURING FILE RESTORE On a WRITE or REWRITE to an alternate-indexed 

OPERATION. WRITE OR REWRITE FUNCTION FOR file, if a duplicate key is encountered ona 

ALTERNATE INDEX FILE FAILED OUE TO DUPLICATE path with no duplicates allowed, the system 

KEY ERROR, AND ATTEMPT TO RESTORE FILE WAS ‘| attempts to delete the record from the primary 

UNSUCCESSFUL. tree and all alternate trees on which it has 
been written. This error occurs if the attempt 
fails unexpectedly. User should attempt 
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SVC CLOSE Cancel Messages 
These messages refer to unexpected error conditions that rarely occur. 


ERROR 

NUMBER MESSAGE ° 

E001 
E002 DEALLOCATION ERR: OFB NOT FOUND. 

E004 CODE = =; UPDATFDR SVC ERR. NO DEALLOCATION. 

E005 UNABLE TO DEALLOCATE BUFFER DUE TO INVALID BUFFER ADDRESS OR 
BUFFER LENGTH IN UFB. 


ace 
bse |-—-reselealanalreentionbaherelsatioedil 
MODE) . 
ADDRESS OR LENGTH IN BUFFER CONTROL TABLE ENTRY. 
FAIL TO LOCATE PROGRAM BUILDALT. UNABLE TO BUILD ALTERNATE INDEXES. 
FILE LABEL NOT UPDATED ( ). USER PROGRAM HAS INCORRECTLY 
MODIFIED THE UFB. 
FILE LABEL NOT UPDATED ( ). VTOC ERROR DETECTED. a 
THE PROGRAM TRIED TO CLOSE THE ADMS FILE WHILE IN THE 


TRANSACTION STATE. 
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5. FILE STATUS (FS) CODES FOR DMS AND ADOMS 


DMS and ADMS return to the user program by means of the RETURN macroinstruction. User registers 2 through 
15 are always restored. Register 0 (RO) is also restored unless UFBEODAD or UFBERRAD is used--RO then 
contains the normal return address. Register 1 (R1) is also restored unless the Read-No-Data option has 
been used--R1 then contains the record address. 


DMS and ADMS indicate the result of the function request through file status bytes UFBS! and UFBS2. These 

bytes generally contain a value of X'30' - X'39', corresponding to the ASCII characters 0 through 9, called 

the File Status (FS) Code. File Status Byte 1 (UFBS1) indicates the general type of file status and File 

Status Byte 2 (UFBS2) indicates a specific item within the group. The various groups are defined as follows: 

- Successful Completion. 

- End of File. 

- Record Not Found (Disk File). 

- 10 Error or Boundary Violation. 

AOMS Codes. 

- Cancel. 

- Time-Out. 

- Special Shared Mode Errors. 

- Miscellaneous - This Group includes errors caused by incorrect user-supplied information; 
e.g., Invalid Function, Invalid Mask, Invalid Length, or Invalid Format. 


OoODMOn oo PhP WON ~ © 
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Following is a list of File Status codes with a description of each code and the conditions under which it 
can occur. 


FILE STATUS FOR NORMAL RETURNS 


FS FUNCTION FILE 
ORGANIZATION 
Successful 
Completion. 


N/A 
Compietion., contains the AID byte. 


Successful Alternate After successfully complet- 
Completion. Indexed i READ KEYED or READ 
an alternate ke 
>» the return code is 02 
indicating at least one more 
record exists with the same 


FILE STATUS FOR UFBEQDADRETURN 


FS FUNCTION FILE 
CODE MEANING REQUEST DEVICE ORGANIZATION MODE CAUSE 
End of File READ NEXT i End of file was reached. 


Reached. 1/0, or 
Shared 


°G 
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FILE STATUS FOR UFBEOOADRETURN (cont'd 


a seta eae 


P| ° “ — 7 ” ra 


Record Key Out of WRITE Indexed 
Sequence or Dupli- 
a aia 


cate Key Found 

During Indexed 

Record Not Found READ Disk Consecutive 
in File. RELATIVE 

mre or S738 rr al eel F- 


File Creation, 
Duplicate Key 

in File. or START 

Primary Extent WRITE Disk Indexed 
Exceeded (Indexed 

File Creation). 

Record Not Found. START Indexed 
(Greater 
Than) or 
(Greater 


code is returned if the 
user program indicates (b 
UFBTFLGEODEOV) that no auto- 
matic volume switch is 
desired. 
The current record key is 
not greater than the pre- 
ceding record key. 


Output 


The record to be added to 
Shared the file has the same key as 
an existing record in the 
file. 
Input or The supplied record number 
1/0 is equal to zero or greater 
than the highest record num- 
ber_ in the file. 
Input, There is no record in the 
I/OX, or file containing a key equal 
o the supplied ke 


Output Primary extent exceeded. 
The record cannot be added 
to the file. The file may be 
closed successfully and then 
opened in I/O Mode to add 
more records. 
Input, The supplied key is greater 
I/O, or than the highest key value 
Shared in the file. 


Value. 

Key Supplied 
Greater Than Key 
Value in File. 
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FILE STATUS FOR UFBERRAD RETURN 


FUNCTION 


Permanent IO Error 
IOsSw 
XXXXKXKKX . 


Workstation Order READ or 
Check. REWRITE 


Boundary Violation 
(Extent Cannot Be 
Obtained). 


Boundary Violation 


(Extent Limit of 
13 Has Been 
Reached). 


OMS Cancel Condi- 
tion Occurred; 
Cancel Message 
Suppressed. 


Shared Time-Out 
Condition. 


Output 
or 
Extend 


Shared 


A physical I/0 operation was 
attempted and a hardware 
error occurred. The 


CHECK. This file status i 
returned for hardware error 
it is not returned for 


There is no more space in 

the file for additional re- 
cords. An additional exten 
is unavailable because 
either the maximum number o 
extents are already allo- 
cated or the extent size is 
not available on volume. 
There is no more space in 

the file for additional re- 
cords (as above) due to ex- 
tent limit (13) exceeded or 
no available extent on vol- 
ume. For Shared mode, 
additional extent may 

be unavailable due to 

mum number of additional 
tents per run already 
allocated. 

User requested suppression 

of all OMS-Cancel messages. 
Process the file in non- 
Shared mode to set the error 
message flag. If a 

error condition code with 
FS=60-019 occurs, refer to 
OMS error code 019 in 
Appendix C. 

This feature will be avail- 
able with the Advanced 
Sharer. 


°S 
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FILE STATUS FOR UFBERRAD RETURN (cont'd 


FUNCTION 


Invalid Key Area READ KEYED 
Found for Read Key | or START 
or Start Key. ~ KEYED 


Invalid Read No- READ NO- 
Data Issued. DATA 


Label Update Oper- 
ation after Last 
Function Was Un- 
successful. 


The Sharing Task 
Has Terminated and 
Must be Restarted. 
Invalid Record 
Size or Area Sup- 
plied for Shared 
Request. 


Update Access 

Denied. REWRITE, 
or DELETE 

Resource Control 

Error. 


Invalid Function REWRITE, 

Sequence. DELETE, or 
READ NEXT 
HOLD 


READ RELATIVE In- READ RELA- 
valid for Variable | TIVE 
Length Records. 


FILE 
ORGANIZATION. MODE 


7 es 


Indexed or Shared 
Consecutive 


wi 


ae 


i. 


nae 


iw 


Indexed IO or 
Shared 


N/A 
N/A 
N/A 
N/A 
N/A 
C ; 


onsecutive Input, 
or I0 


UFBKEYAREA does not point to 
the key embedded in the rec- 
ord; i.@., specifies the ke 
has a value of one (for 
length of five but it actu- 
ally has a value of two for 


a Read No- 


Internal error by DMS. The 
file label (FDR1) is updated 
whenever any of the follow- 
ing fields are modified b 
DMS: Root Block Numbers; 
First Data Block Number; or 
Count of Levels in the (Pri- 
mary) Index. If UPDATFOR i 
unsuccessful, FS equals 82 

is returned. 

Sharing task is functioning 
incorrectly. Must IPL the 
System to restart Sharer. 
User Attempted to rewrite a 
variable tength record whose 
length is greater than the 
maximum record size speci- 
fied in the vToc. 

User Attempted to update a 
file in Shared mode but has 
Read-Only access. 

Incorrect sequence of Shared 
function requests; e.g., At- 
tempting to do a Start 

on a file while another file 
is already held. 

Invalid function sequence 
similar to consecutive file 
case above occurred. Also 
returned if Read Next Hold 


for fixed-length consecutive 
files. 
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FILE STATUS FOR UFBERRAD RETURN (cont'd) 


FS FUNCTION FILE 


REQUEST DEVICE ORGANIZATION 
Invalid Function N/A N/A N/A Valid function requests are 
Request. described for the given com 
: binations of device class, 
open mode and file i 
tion supported by 
After a file has 
opened, an invalid functio 
request is flagged with F 
equals 95. Exampte: 
attempting to write a record 
while the file is opened in 
Input mode. 
N/A 
N/A N/A 
N/A N/A 


Record was not read with the 
HOLD option. For Shared 
Mode, an intervening READ 
with HOLO on another file 
may have released the HOLD. 
A function sequence error 
exists since the record can- 
not be rewritten unless it 

is ‘HELD',. 


REWRITE Function REWRITE Disk Consecutive Consecutive files can be re- 
Invalid for Con- oe el el written only for fixed- 
secutive File with length records. 
Compressed Records. 
N/A 
% Issued on Alter- 
nate Indexed File. 
READ NEXT Issued N/A 
on Indexed File 
when Current Posi- 
tion Was Undefined. 
Invalid Function N/A 
Issued in Shared 
Invalid START START Consecutive 
Function (Modifier or Indexed 
Primary Key Value REWRITE Indexed or 
Was Changed when Alternate ue of the Primary Key while 
Rewriting an Indexed rewriting a record. 
Indexed Record. 


Invalid Function. REWRITE 
Sequence. 


Invalid Function 
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FILE STATUS FOR UFBERRAD RETURN (cont'd) 


FS FUNCTION FILE 


Invalid Disk Add- 
ress Detected. 


Write Operation 
Attempted on Write- 
Protected Disk. 


Invalid Data Area READ, 
Location or Align- | REWRITE, 


ment (10 Command or WRITE 
error). 


Same as 96 above. READ or Workstation! N/A 
REWRITE 


Invalid Length REWRITE Indexed 
when Rewriting 

Variable Length 

Record. 


Same as 97 above. REWRITE 


Invalid Length WRITE N/A 
Supplied when 

Writing Variabie- 

Length Record. 


Input, 
I0, or 
Output 
(Block 
Level) 


Output, 
Shared, 


I0, or 
Extend 


Error usually not caused by 
user program. Error ca 
occur for invalid disk ad 
dress in the extent 
(possibly caused by 

rect device arrangement 
SYSGEN). This file status 
is returned only if the IOSW 
indicates invalid command 
data address. Under 

OMS supplies the buffer 

and command, thus, FS 

is a rare error under RAM. 

An attempt was made to write 
to an open write-protected 
diskette (this can occur i 
a user remounts a diskette 
changing it to write-pro- 
tected but not using the 
MOUNT command 

Data area location is inval- 
id or alignment is not on a 
page boundary. Data area 
location is checked with 

data area length to ensure 
that only the stack, static 
area, or buffer area is 

being used. 

Invalid data area location 

or alignment (word align- 
ment required. 
Invalid length is indicated 
when attempting to rewrite a 
variable-length record whose 
length is longer than the 
value established in 
UFBRECSIZE. 

Invalid, cannot change re- 
cord length of a consecutive 
file. 

Invalid length is indicated 
when attempting to write a 
variable-length record whose 
length is greater than the 
value established in 
UFBRECSIZE. 
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FILE STATUS FOR UFBERRAD RETURN (cont'd) 


FS FUNCTION FILE 


CODE MEANING 77 ial MODE CAUSE 


LT-0 


Invalid Record- 
Prefix Found in 
Variable-Length 
Record. 


Invalid Length 
Specified for 10 
Operation. 


Invalid Alternate WRITE or 
Tree Mask Supplied | REWRITE 
on Write or Re- 
write Function. 


Invalid Format 
Found for Current 
File Block. 


Printer, 
Tape, or 
Workstation 


Alternate 
Indexed 


Output, 
I0, or 
Shared 


Error encountered while DMS 
is attempting to extract a 
variable-length record from 
its buffer. Error should 
not normally be encountered 
by the user. 
Length specified is not val- 
id for the device. For the 
printer, length is invalid 
if it equals zero or is’ lar- 
ger than the length speci- 
fied at SVC OPEN. For the 
workstation, length 
invalid if data length 
starting row cause screen 
overflow. For tape, tlength 
is invalid if a long block 
or a short block (with = non- 
integral number of records) 
is read. 
Aiternate key mask refer- 
ences a nonexistent alter- 
nate key. For Write or Re- 
write, the user-supplied 
mask must indicate valid 
ALT-trees and the alternate 
key fields must fall within 
the record; otherwise, FS=98 
is returned: NOTE: A mask 


A block within a variable= 
length record file has an 
invalid prefix, a 

record has an 

prefix, or a compressed 
record has an invalid form-t 
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FS=49, 


All file status codes peculiar to ADMS fall within the range of FS=40 to 
These codes and their meanings are as follows: 


FUNCTION FILE 


Attempt to Update 

an ADMS File while | REWRITE, 
Not in Transaction | DELETE 
State. 

ADMS Mapping Con- 

trol Table (MCC) WRITE, 
Error Detected. REWRITE, 


AOMS Data Item 
Integrity Violated.| REWRITE 


Unable to Log Re- 
cord Image for REWRITE 
AOMS Recovery. 


View Access Block 
(VAB) Information 


Not Consistent 
with UFB. 


Unable to Do Oper- |N/A Shared 
tion, File Previ- 

ously Crashed. 

Unabte to Perform WRITE, N/A 
ADMS Data Conver- REWRITE 

sion Due to Invai- 

id Oata Format. : 

Entire ADMS File WRITE, Alternate- Shared 
Must Be Held for REWRITE, Indexed 
Shared Update with | DELETE ADMS 

Unique ALT Key. 


User error in order of 
operation. 


Internal error in MCC table; 
unable to perform data 
mapping. 


Data item failed Integrity 
Check (ICK). 


DTI SVC failed while at- 
tempting to map the record 
image to sharer for logging 
to audit file. 

VAB improperly set up 
(System error). 


A crash condition has been 
detected for the data base. 
No request except CLOSE will 
be honored. 

Unable to perform data map- 
ping due to invalid data. 
Example: attempt to convert 
signed ASCII to binary but 
sign byte is invalid. 

Error in user's hold logic. 
ADMS file with recovery has 
ALT index with no dups; user 
faited to hold entire file 
when making date. 
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Summary of Changes 


For lst Edition of VS Operating System Services* 


NEW FEATURES 305-315 


. Labelled tape support: 
- Changes to DMS functions 
and OPEN and CLOSE 


Telecommunications Support 

~ New Macro: TCOPTION 

~ Changed Macros: READ 
START, UFBGEN, WRITE 

~ Changed SVCs: OPEN 

CLOSE, CHECK 


127 


100, 121, 131, 142 


177, 182, 199 


. New Macrointructions 


- DISMOUNT 63 
- HALTIO 77 
- MOUNT 87 
~- READFR 104 

= SET 116 


TCOPTION 127 


DOCUMENTATION 
CHANGES 


- Documentation of the follow- 
ing macroinstructions is not 
included in this manual: 

- FREEMEM 
~ GETMEM 
- LOW 
SEND 
WAIT 


See VS System 


Development Guide 
(800-1108SD-01) 


Documentation of the follow- 
ing SCVs is not included in 
this manual: 


See VS System 


Development Guide 
(800-1108SD-01) 


- WAIT - GETDISK 

- SEND - FREEDISK 
~ FIX/UNFIX - CREATFDR 
- CETMEM - UPDATFDR | 
- FREEMEM - PLEASE 

- DTI ~ MWAIT 


SEIZE/RELEASE 


* This manual replaces the VS System Programmer's Guide. The 
summary of changes refers to differences between this manual and 


the last edition of the System Programmer's Guide 
(Pub. #800-1103SP-03) . 
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Description Affected Pages 


. Documentation of the follow- | See VS System 
ing control blocks is not Development Guide 
included in this manual: (800-1108SD-01) 

CMSG PRB 
DBTB 
DPT 
ETCB 
FLUB 
FMSG 
TORE 
MCB 
OFB 
PFB 
PFSA 
PFT 


TECHNICAL . Changes to EXTRACT Macro and 
CHANGES SVC 


Changes to HALTIO SVC 194 


- Revisions and clarifications 
of DMS messages 348 ~ 354 


Changes to EXTRD control 
Block 


EDITORIAL Miscellaneous Editorial 
CHANGES Changes 


DH-2 


SUMMARY OF CHANGES FOR 2ND EDITION OF 
VS OPERATING SYSTEM SERVICES MANUAL 


RELEASE 4 SUPPORT CHANGES CEXIT 53 through 54.1 
CHECK 55 through 56.1 
CLOSE 57 
CREATE 38 
DISMOUNT 63, 63.1 
EXTRACT 64, 67 through 69.1 
FMTLIST 70 
HALTIO 77 through 73.1 
KEYLIST 79 through 81.1 
MOUNT 87 through 89 
READVTOC 106.1 through 106.4 
REGS 107 
SET 116 through 119 
SUBMIT JOB | 126.1 through 126.6 
RETURN CODES 126.7, 126.8 
XMIT 148, 148.1 
EDITORIAL CHANGES IORE (1/0 Request Element) | 171.1, 171.2 


OFB (Open File Block) 171.3, 171.4: 


UFB (User File Block) 173.1 through 173.12 


READVTOC SVC 204, 205 
MOUNT 231 
STATIC BLOCK 326, 327, 328 


DATANAME SUBBLOCK 338 
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Summary of Changes 
for the 


VS Operating System Services Addendum 
(800-11070S-02.01) 


NEW 355-367 
FEATURE 


TECHNICAL 
CHANGES 


Chapter 2 


External Names in Code 


Chapter 4 


BCTGEN Buffer Pool 
CEXIT 

CHECK Operand 

CXT Suffix 

DELETE Syntax 
DESTROY Operand 
EXTRACT 

FREEBUF Return Code 
GETBUF 

GETPARM Operand 

MSGLIST Operand 

OPEN Syntax and Operand 


RENAME Syntax, Operand, 108, 109 
Return Code 109.1 

REWRITE Coding Example 113 

SCRATCH Syntax 114 

SET Operand 117 

SUBMIT Syntax 126.1 


XI0 Coding Example 147 


Chapter 5 


OFB Fields and Flag 
TPLAB 


171.3, 171.4 
172 


DH-4 


TECHNICAL UFB Open Format Error 173.4 
CHANGES WP and Workstation 173.5, 173.7 
UFBFPCLASS & UFBFILENAME | 173.7 
UFBXCODE 173.10 
WP File Control 173.10 
7-Track Tape 173.12 


Chapter 6 


OPEN File & Volume Names 
UFBFS2XFORMAT 
XIO0 Halt I/O Queue 
Return Codes 
GETBUF Return Codes 
FREEBUF Return Code 
HALTIO Input 
CHECK Input 
Unsolicited Interrupt 
Function 6 
READVTOC Return Code 
GETPARM Uppercase Alphanum 
Alphanumeric Limited 
RENAME Return Code 
EXTRACT OS Version Number 
EXTRDIDTAPEVOL 
MOUNT Input Parameter 
Return Code 
SET Procedure Keyword 
XMIT NOWAIT & OTHERTASK 
CREATE Privileged & GETMEM 
CEXIT NODEBUG & HELP 
DISMOUNT GETMEM 


EDITORIAL Miscellaneous 53, 58, 74, 

CHANGES Editorial Changes 76, 83, 90, 
93, 97, 98, 
106.2, 106.3, 
106.4, 109, 
109.1, 110, 
113, 114, 115, 
126.3, 126.4, 
126.5, 126.6, 
173.10, 202, 
203, 222, 241, 
327 
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Access Methods 
BAM (Block Access) .... 
PAM (Physical Access). .... 
RAM (Record Access). . 2. « « « 
Selection Criteria ..... . 


Additional Extents for a File (FDR2) .. 


Address Translation. ...... 


Allocate Memory Storage (GETHEAP) ... 


Alternate File Error Log... . 
Alternate Index Descriptor Block 
Alternate Indexed File 
AXD1 Block . .... 2 « «© « « 
Compared with Indexed File . . 
Error Log. . . « « «5 © «© «© « 
Fields in UFB. . ... eee - 
Internal Representation. ... 
1/0 Functions 
Delete. . . . 2. 2. 2 © eo 
Openers so: 2a) ac Gt ee ees 
Read. «2. 1 se se we wo ee 
Rewrite . . 1. 2 1 6 e «© oe 
SEAM. 64 6. es sd ow Sy eh ce, Ok 
MEIC 5: oe aw ee el ee 
Output Mode File Attributes 
Error Log . 1. + 2 « « © ee 
Specification .....e-. 
AXD1 (Alternate Index Descriptor 
. AXDGEN Macro ....... a ee 


BAM (See "Block Access Method") 
BCE (Buffer Control Entries) .. 
BCTBL (Buffer Control Table) . . 
BCTGEN Macro ....++ + © « « 
Block Access Method (BAM) Files 
Buffer Size Specification. .. 
File Size Specification. ... 


(AXD1) . 


Block). 


e e es ° 


Function Requests and Modifiers. ... 


General Description. ..... 
Information Needed at CLOSE. . 
Record Size Specification. .. 
Blocks (See "Control Blocks") 
Disk i File. -%. 2, sé“ ee eS Par 


e e e e 
es e 
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Buffer Control Entries (BCE) .. 
Buffer Control Table (BCTBL) . . 
BUILDALT Program to Fix Error Log. . . 


CALL Macro. ......6. 
Call a Subroutine (CALL) . 

Argument Lists ..... 
CANCEL Macro ....... 
CANCEL (SVC 16)... ... 
Cancel Program (CANCEL). . 
Cancel Exit (CEXIT).... 
Cancel Messages 
Function Request . . 


DMS 
SVC 
SVC 


- CEXIT 


CEXIT 
CHECK 
CHECK 
Check 
Clock 
CLOSE 
CLOSE 
Close 
CLOSE 


CLOSE. .... 
OPEN 6) a So as 
Macro. ... . 
(svc 39)... 
Macro. . « « e 
(svC 17)... 


for Event Occurrence 


Interruptions. 
Macro. . . « » 
(SVC 1). ... 
File (CLOSE) . 


SVC Cancel Messages. 
Compression Option for RAM 
Consecutive Disk File Records 
Fixed Length .......6. 
Variable Length. ...... . 
Control Blocks 
(AXD1) Alternate Index Descriptor Block. 
(BCE) Buffer Control Entries ...... 
(BCTBL) Buffer Control Table... . 
(EXTRD) Extract SVC Result Area. . . 
(FDR1) File Descriptor Record Format 
(FDR2) File Descriptor Record 


Files 


e e e 


Format 2 -- Additional Extents. . 


(IORE) I/O Request Element ..... 
(OFB) Open File Block. . ... ses 
(TPLAB) Tape Labels. . . 


(TPLB2) Tape Labels -- 
(UFB) User File Block. . 


General Description . 
(VOL1) Volume Labels . . 
CREATE Macro... . 


CREATE (SVC 37). .... 
Create Intertask Message 


Secondary . . 


Port (CREATE) 
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2 «© « 6-70 
4-17, 6-70 


Data Area Macroinstruction Format. ... . 
Data Management Support SVCs: CHECK, XIO 
Data Management System (See "DMS") 

Dataname Subblock. ... 2. +o « « «© e © « « 
Deallocate Memory Storage .....+.e-. 
Default File Specifications. ....... 
DELETE Macro . ...-« +s ¢ «© © e © © © 2 
Delete Function (DMS RAM). . .. . «6 « «s 
Delete Function (DMS Indexed). ...... 
Delete Record from Index (DELETE)... .. 
DESTROY Macro. . . « « « «© © © © © we ew 


DE STROY (SVC 3 8) e e e e e e e e e 2 6 
Destroy Intertask Message Port (DESTROY) ; 


Disk Storage Description... ....s.s-. 


Extent Organization. . . 2. . « « e « « « 


Volume Label s e e e e e e e e e ® e ° s 


Volume Table of Contents .....e«e«- 


DISMOUNT Macro . . . 2 « 6 © © «© © © © ec 
DI SMOUNT (SVC 41) 6 e e s s e e e e 6 es . e 


Dismount Disk or Tape Volume (DISMOUNT). . 


DMS (Data Management System) 
Fatal Errors . . 1. « 2 © © «© e © w@ © ow 
Function Requests 
Cancel Messages . . « « « «© ew» we wo 


Entry ° e e e a e e e ° e e e e e es e 


File Status Return Codes. ...... 
Magnetic Tape Support. . . . . . « « « » 
Close Files is Se mice ee ee ee ce 
Tnitialising, o6 6a el 6 ew ce ee 
Labels i. a: 6 ee We Os OO 
Mount/Dismount. . . 2. 1 « « «©» «© «© « 
Multiple Volume... . 2. 6 2 2» eo « 
Open Bile. 6638.66 wt ee. we Se: 
Read. « «6 ss se se ew te tw 
SEAR: 6. te Sle. Se es eo Se a eG 
WILC6 ao oe Be ww WS ee Ses ww 
TOLPACK i <¢- We: cee b- @e ees a ce eS 
Messages 
SVC CLOSE Cancel Messages ...... 
Function Request Cancel ....... 
SVC OPEN Cancel Messages. oe ee Oe 
SVC OPEN Respecify Massages ee a eS 
Printer Support... 6 e646! we 
Workstation Support. . . .. 2. 2. 2. ee. 
Read Request. . . 2. 2. 2. « « «© «© © «@ 
RGEWCite? go> ink Gi ee a ee 
Start Function Request. ...... 
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